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, orproject.members.write. A missing scope returns403 INSUFFICIENT_SCOPE. - The workspace ID or project ID that you manage.
X-API-Key header or as Authorization: Bearer <key>. The API rejects user session tokens and SDK tokens with 401.
Workflow and use cases
- List the workspace roles and project roles. Use
assignableByCallerto see which roles your key can assign. - List the workspace projects to get project IDs.
- Invite people to the workspace. Each person starts as
pendingand gets access after they accept and sign in. - Add active workspace members to projects with a project role.
- Look up, update, or apply lifecycle actions to members as their access changes.
- Remove members from projects or the workspace when they leave.
List of endpoints
Behavior and limits
- A key can assign only
builtin.workspace.restricted_memberandbuiltin.workspace.workbench_managerat workspace level. At project level it can assignbuiltin.project.developer,builtin.project.tester,builtin.project.viewer, andbuiltin.project.workbench_manager. Owner, Admin, Auditor, and custom roles are never assignable by a key. - Batch endpoints accept up to 100 items. They return
201when every item succeeds and207when any item fails. Each item carries its ownoutcome. - Send an
Idempotency-Keyheader on every write so a retry replays the first result. Send theETagfrom your last read inIf-Matchon updates to avoid overwriting concurrent changes. - Every response carries an
X-Request-Idheader. 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
429with aRetry-Afterheader. - Invitation emails are limited to 500 per hour for each workspace and 3 per address in 24 hours.