> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# User management API overview

> Use the user management API to provision, update, and remove workspace and project members from an identity provider, HR system, or script with a platform API key.

Use the user management API to provision, update, and remove workspace and project members from an identity provider, an HR system, or a script. You invite people to a workspace, add them to projects, change their roles, and remove them when they leave.

## Prerequisites

* A workspace platform key (`abl_ws_…`). A workspace Owner or Admin creates it under **Settings > Secrets > Platform Keys**. Project endpoints also accept a project platform key bound to that project.
* The scopes that the endpoints you call need: `workspace.members.read`, `workspace.members.write`, `workspace.roles.read`, `project.members.read`, or `project.members.write`. A missing scope returns `403 INSUFFICIENT_SCOPE`.
* The workspace ID or project ID that you manage.

Send the key in the `X-API-Key` header or as `Authorization: Bearer <key>`. The API rejects user session tokens and SDK tokens with `401`.

## Workflow and use cases

1. List the workspace roles and project roles. Use `assignableByCaller` to see which roles your key can assign.
2. List the workspace projects to get project IDs.
3. Invite people to the workspace. Each person starts as `pending` and gets access after they accept and sign in.
4. Add active workspace members to projects with a project role.
5. Look up, update, or apply lifecycle actions to members as their access changes.
6. Remove members from projects or the workspace when they leave.

## List of endpoints

| Use case | Help article | Scope | Purpose |
| :- | :- | :- | :- |
| Find roles | [List workspace roles](https://koreai.mintlify.site/agent-platform/api-reference/user-management-list-roles) | `workspace.roles.read` | List the built-in workspace roles and whether a key can assign each one. |
| | [Get a workspace role](https://koreai.mintlify.site/agent-platform/api-reference/user-management-get-role) | `workspace.roles.read` | Get one built-in workspace role with its permissions. |
| | [List assignable project roles](https://koreai.mintlify.site/agent-platform/api-reference/user-management-list-project-roles) | `project.members.read` | List the built-in project roles and whether a key can assign each one. |
| Find projects | [List workspace projects](https://koreai.mintlify.site/agent-platform/api-reference/user-management-list-projects) | `project.members.read` | List the workspace's projects with their member counts. |
| Onboard | [Create workspace member invitations](https://koreai.mintlify.site/agent-platform/api-reference/user-management-invite-members) | `workspace.members.write` | Invite up to 100 people to the workspace in one request. |
| | [Add project members](https://koreai.mintlify.site/agent-platform/api-reference/user-management-add-project-members) | `project.members.write` | Add up to 100 active workspace members to a project with a role. |
| Look up | [List workspace members](https://koreai.mintlify.site/agent-platform/api-reference/user-management-list-members) | `workspace.members.read` | List workspace members with cursor pagination and filters. |
| | [Search workspace members](https://koreai.mintlify.site/agent-platform/api-reference/user-management-search-members) | `workspace.members.read` | Search workspace members with filters in the request body to keep email addresses out of URLs. |
| | [Get a workspace member](https://koreai.mintlify.site/agent-platform/api-reference/user-management-get-member) | `workspace.members.read` | Get one workspace member with their project memberships. |
| | [List project members](https://koreai.mintlify.site/agent-platform/api-reference/user-management-list-project-members) | `project.members.read` | List the members of a project with their roles. |
| | [Get a project member](https://koreai.mintlify.site/agent-platform/api-reference/user-management-get-project-member) | `project.members.read` | Get one project member and their role. |
| Change | [Update a workspace member](https://koreai.mintlify.site/agent-platform/api-reference/user-management-update-member) | `workspace.members.write` | Change a workspace member's role or external ID. |
| | [Apply a workspace member lifecycle action](https://koreai.mintlify.site/agent-platform/api-reference/user-management-member-actions) | `workspace.members.write` | Apply a lifecycle action, such as suspend or reactivate, to a workspace member. |
| | [Update a project member role](https://koreai.mintlify.site/agent-platform/api-reference/user-management-update-project-member) | `project.members.write` | Change a member's project role. |
| Offboard | [Remove a workspace member](https://koreai.mintlify.site/agent-platform/api-reference/user-management-remove-member) | `workspace.members.write` | Remove a member from the workspace and its projects, or revoke an invitation. |
| | [Remove a project member](https://koreai.mintlify.site/agent-platform/api-reference/user-management-remove-project-member) | `project.members.write` | Remove a member from a project. |

## Behavior and limits

* A key can assign only `builtin.workspace.restricted_member` and `builtin.workspace.workbench_manager` at workspace level. At project level it can assign `builtin.project.developer`, `builtin.project.tester`, `builtin.project.viewer`, and `builtin.project.workbench_manager`. Owner, Admin, Auditor, and custom roles are never assignable by a key.
* Batch endpoints accept up to 100 items. They return `201` when every item succeeds and `207` when any item fails. Each item carries its own `outcome`.
* Send an `Idempotency-Key` header on every write so a retry replays the first result. Send the `ETag` from your last read in `If-Match` on updates to avoid overwriting concurrent changes.
* Every response carries an `X-Request-Id` header. Quote it to Kore.ai Support.
* Responses use the envelope `{ "success": true, "data": … }` or `{ "success": false, "error": { "code", "message", "details" } }`.
* Per key, the limits are 300 reads per minute, 60 writes per minute, 300 removals per minute, and 5 requests in flight. Exceeding a limit returns `429` with a `Retry-After` header.
* Invitation emails are limited to 500 per hour for each workspace and 3 per address in 24 hours.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.