> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.cdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Management API

> The Connect AI Management API provides programmatic control over enterprise platform administration. Use it to manage users, service accounts, and roles without manual UI operations.

The Management API base URL is `https://cloud.cdata.com/api/v1/admin`.

<Note>
  The Management API is currently in beta as part of a design partner program.
</Note>

## Authentication

All Management API requests must use OAuth 2.0 client credentials of Client Id and Client Secret. Existing PATs and Basic Auth credentials do not work with this API.

**Step 1: Request a bearer token**

```bash theme={null}
curl -X POST https://cloud-login.cdata.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<ClientId>&client_secret=<ClientSecret>"
```

**Step 2: Call the Management API**

```bash theme={null}
curl https://cloud.cdata.com/api/v1/admin/users \
  -H "Authorization: Bearer <access_token>"
```

## Pagination

Collection responses use cursor-based pagination. All collection responses share the same envelope:

```json theme={null}
{
  "items": [ ... ],
  "limit": 20,
  "next_cursor": "eyJpZCI6IjEyMyJ9"
}
```

| Field          | Description                                                                                                    |
| :------------- | :------------------------------------------------------------------------------------------------------------- |
| *items*        | Array of result objects.                                                                                       |
| *limit*        | The maximum number of items per page as requested.                                                             |
| *next\_cursor* | Pass this value as the `cursor` query parameter to retrieve the next page. `null` when no further pages exist. |

Total counts are not returned. Iterate using `next_cursor` until it is `null`.

## Errors

Error responses use a consistent structure:

```json theme={null}
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "The specified user does not exist."
  }
}
```

The `code` field is a `SCREAMING_SNAKE_CASE` string suitable for programmatic handling. The `message` field is a human-readable description.

## Identities

The Management API manages two types of identities.

### Users

Human users are provisioned and lifecycle-managed by SCIM when your organization has SCIM configured. The Management API handles direct overrides (for example, contractors or break-glass accounts) and atomic deprovisioning. Users created directly via the API carry `scim_managed: false`.

### Service Accounts

Service accounts are machine identities for CI/CD pipelines, IaC tooling, and Terraform automation. Service accounts are not SCIM-owned and authenticate via OAuth 2.0 client credentials using the `client_id` returned on creation.

## Access Model

A principal's effective access is the union of the following independent sources:

* **Direct role assignments**–assigned individually to a user or service account (via [Assign User Role](/en/API/Assign-User-Role) or the equivalent service account endpoint).
* **Group-derived role assignments**–inherited via SCIM group membership (users only).
* **Direct permissions**–resource-level grants assigned individually (via [Assign User Permission](/en/API/Assign-User-Permission) or the equivalent service account endpoint).

### Roles

Two role types exist in Connect AI:

| Type          | Description                                                    |
| :------------ | :------------------------------------------------------------- |
| `system_role` | Built-in, non-modifiable. Defines a fixed set of capabilities. |
| `access_role` | Custom role with explicit resource-level permissions.          |

The account-wide `admin` system role is assigned via `POST /users/{id}/roles` or `POST /service-accounts/{id}/roles`.

<Note>
  Custom role management (create, update, delete access roles) is not yet available in the Management API.
</Note>

### Built-In System Roles

| Role               | Scope        | Description                                                                                        |
| :----------------- | :----------- | :------------------------------------------------------------------------------------------------- |
| `admin`            | Account-wide | Full administrative control over the entire organization.                                          |
| `workspace_admin`  | Workspace    | Full control over a workspace: combines `connection_admin` and `user_admin` within that workspace. |
| `connection_admin` | Workspace    | Manage connections within a workspace.                                                             |
| `user_admin`       | Workspace    | Manage users within a workspace.                                                                   |
| `query`            | Workspace    | Execute queries against connections in a workspace.                                                |
| `oem_admin`        | Workspace    | OEM administration within a workspace.                                                             |
| `oem_viewer`       | Workspace    | OEM read access within a workspace.                                                                |
| `service_user`     | Workspace    | Service-level access within a workspace.                                                           |

<Note>
  Workspace-scoped role assignment endpoints are not yet available. Currently, only the account-wide `admin` role can be assigned via the Management API.
</Note>