Roles Endpoints

The Roles API provides endpoints for managing discovered roles, role mining, and policy generation.

Base URL

All endpoints are relative to /api/v1/roles.

---

List Roles

Retrieve all roles.

GET /api/v1/roles

Response

{
  "roles": [
    {
      "id": "role-123",
      "name": "Engineering - Senior Developer",
      "department": "Engineering",
      "title": "Senior Developer",
      "owner_count": 25,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

---

Get Role

Retrieve details for a specific role.

GET /api/v1/roles/{id}

Path Parameters

Parameter	Type	Description
id	string	Role ID

Response

Returns the complete role object.

---

Create Role

Create a new role.

POST /api/v1/roles

::: note Administrator Only This endpoint requires Administrator role. :::

Request Body

{
  "name": "Finance - Analyst",
  "department": "Finance",
  "title": "Financial Analyst"
}

Response

Returns the created role object.

---

Update Role

Update an existing role.

PUT /api/v1/roles/{id}

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Role ID

Response

Returns the updated role object.

---

Delete Role

Delete a role.

DELETE /api/v1/roles/{id}

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Role ID

Response

Returns 204 No Content on success.

---

Role Settings

Get Role Settings

GET /api/v1/roles/settings

Response

{
  "mining_columns": ["department", "title"],
  "auto_regenerate": false,
  "minimum_owner_count": 2
}

Update Role Settings

PUT /api/v1/roles/settings

::: note Administrator Only This endpoint requires Administrator role. :::

Request Body

{
  "mining_columns": ["department", "title", "location"],
  "auto_regenerate": true
}

---

Regenerate Roles

Trigger role regeneration based on current settings.

POST /api/v1/roles/regenerate

::: note Administrator Only This endpoint requires Administrator role. :::

Response

{
  "status": "queued",
  "message": "Role regeneration initiated"
}

---

Get Role Statistics

Retrieve role statistics.

GET /api/v1/roles/statistics

Response

{
  "total_roles": 150,
  "total_owners_with_roles": 1200,
  "avg_owners_per_role": 8,
  "roles_with_policies": 45
}

---

Get Owner Columns

Retrieve available owner columns for role mining.

GET /api/v1/roles/owner-columns

Response

{
  "columns": [
    { "name": "department", "type": "string", "sample_values": ["Engineering", "Finance"] },
    { "name": "title", "type": "string", "sample_values": ["Developer", "Analyst"] },
    { "name": "location", "type": "string", "sample_values": ["New York", "London"] }
  ]
}

---

Role Analysis

Analyze All Roles

POST /api/v1/roles/analyze-all

::: note Administrator Only This endpoint requires Administrator role. :::

Response

{
  "status": "queued",
  "message": "Role analysis initiated"
}

Analyze Single Role

POST /api/v1/roles/{id}/analyze

Path Parameters

Parameter	Type	Description
id	string	Role ID

Get Role Analysis

GET /api/v1/roles/{id}/analysis

Response

{
  "id": "analysis-123",
  "role_id": "role-123",
  "common_applications": [...],
  "common_groups": [...],
  "risk_assessment": {...},
  "created_at": "2024-02-01T10:00:00Z"
}

Get Analysis History

GET /api/v1/roles/{id}/analysis/history

---

Role Relationships

Get Role with Owners

GET /api/v1/roles/{id}/owners

Response

{
  "role": {...},
  "owners": [
    {
      "id": "own-123",
      "name": "John Doe",
      "email": "john.doe@company.com"
    }
  ]
}

Get Role Applications

GET /api/v1/roles/{id}/applications

Get Role Groups

GET /api/v1/roles/{id}/groups

Get Policies by Role

GET /api/v1/roles/{id}/policies

---

Generate Policy from Role

Generate a policy based on a role's access patterns.

POST /api/v1/roles/{id}/generate-policy

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Role ID

Response

Returns the generated policy object.

---

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Role does not exist
500	Internal Server Error

---

Related Topics

• Policies API - Policy management endpoints
• Owners API - Owner management endpoints
• Role Configuration - User guide
• API Reference - Complete API index