---
title: Admin Roles API
path: reference/api/admin-roles
status: published
---

# Admin Roles API

Reference for the `Admin Roles` endpoint group — 6 endpoints.

Generated from the live OpenAPI spec. Re-run `_generate_api_reference.py` after backend changes.

## Authentication

All endpoints require a Bearer JWT in the `Authorization` header unless noted otherwise. See [Concepts → Tokens and scopes](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/reference/oauth-endpoints) for how to obtain one.

## Endpoints

### **GET** `/api/v1/admin/admin-roles/`

_List Admin Roles_

List all admin role assignments.

Only accessible by Super Admins.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `role` | query | no | `string` \| `null` | Filter by role type |
| `user_id` | query | no | `string` \| `null` | Filter by user |
| `is_active` | query | no | `boolean` \| `null` | Filter by active status |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/admin/admin-roles/`

_Create Admin Role_

Assign an admin role to a user.

Only accessible by Super Admins.

Required fields:
- user_id: The user to assign the role to
- role: SUPER_ADMIN, PARTNER_ADMIN, or TENANT_ADMIN

Conditional fields:
- partner_id: Required for PARTNER_ADMIN
- tenant_id: Required for TENANT_ADMIN

Optional fields:
- expires_at: When the role expires (ISO format)

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/json` → object

**Responses:**

| Status | Body |
|---|---|
| `201` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/admin-roles/user/{user_id}`

_Get User Admin Roles_

Get all admin roles for a specific user.

Only accessible by Super Admins.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `user_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/admin/admin-roles/{role_id}`

_Delete Admin Role_

Revoke an admin role assignment.

Only accessible by Super Admins.
Cannot delete your own Super Admin role.

If cleanup_orphaned_user is True (default), will also soft-delete the user if:
- They have no remaining admin roles after this deletion
- They exist in multiple tenants with the same email (duplicate admin user)
- They have never logged in

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `role_id` | path | yes | `string` |  |
| `cleanup_orphaned_user` | query | no | `boolean` | If true, delete the user if they have no remaining admin roles and appear to be admin-only |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/admin-roles/{role_id}`

_Get Admin Role_

Get a specific admin role assignment.

Only accessible by Super Admins.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `role_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **PATCH** `/api/v1/admin/admin-roles/{role_id}`

_Update Admin Role_

Update an admin role assignment.

Only accessible by Super Admins.

Updatable fields:
- is_active: Activate or deactivate the role
- expires_at: Set or update expiration

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `role_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/json` → object

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

## Schemas

Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.

### `HTTPValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `detail` | array of [`ValidationError`](#schema-validationerror) | no |  |

### `ValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `loc` | array of `string` \| `integer` | yes |  |
| `msg` | `string` | yes |  |
| `type` | `string` | yes |  |