Management API — Getting Started

Create and scope API keys, authenticate requests, introspect your key, check seat availability, and understand error responses.

Overview

The Management API lets you provision users, manage room memberships, query seat capacity, and configure outbound webhooks — all programmatically from your identity provider, HR system, or automation tooling. Two interfaces are available: a SCIM 2.0 endpoint for IdP-native provisioning, and a JSON REST API for direct integration.

Authentication

Every request must include your API key in the Authorization header using the Bearer scheme. Keys are tenant-scoped and carry one or more permission scopes that control which endpoints they can reach.

Authorization: Bearer <your-api-key>

Create and manage API keys from Settings → API Keys in your organisation's dashboard. The full key value is shown exactly once on creation — copy and store it securely before closing the page.

Available Scopes

Each API key holds one or more scopes. A request that requires a scope the key does not hold returns 403 Forbidden. Assign the minimum set of scopes each key needs.

• scim:read — List and retrieve users and groups via the SCIM 2.0 endpoint.
• scim:write — Create, update, and delete users and groups via SCIM 2.0.
• api:users:read — Read users via the native Management API.
• api:users:write — Update and deactivate users via the native Management API.
• api:rooms:read — Read rooms and their members via the native Management API.
• api:rooms:write — Manage room memberships via the native Management API.
• usage — Query seat availability and provisioning capacity.
• webhooks — Create, update, delete, and test outbound webhook registrations.

Introspecting Your Key

GET /me returns metadata about the authenticated API key — its scopes, description, and the organisation it belongs to. Use this to validate your integration configuration before sending provisioning requests.

GET /me
Authorization: Bearer <your-api-key>

// Response — 200 OK
{
  "key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_slug": "acme",
  "tenant_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
  "scopes": ["scim:read", "scim:write", "webhooks"],
  "description": "Okta provisioning key"
}

Seat Availability

GET /usage returns the current seat usage for your organisation. Use this to check capacity before bulk-provisioning users. Requires the usage scope.

GET /usage
Authorization: Bearer <your-api-key>

// Response — 200 OK
{
  "seat_capacity": 100,
  "seats_provisioned": 72,
  "seats_available": 28
}

Key Rotation

Keys do not expire automatically. To rotate a key, create a new key with the same scopes, update your integration to use the new key, then revoke the old key from the dashboard. There is no downtime during the swap — both keys are valid until the old one is deleted.

Rate Limiting

Requests are rate-limited to 600 per minute per API key. Responses that exceed the limit return 429 Too Many Requests. SCIM Bulk requests count as a single request against the rate limit regardless of how many operations are in the payload.

Error Responses

All errors return a JSON body with an error field. SCIM errors additionally follow RFC 7644 format with a schemas field.

• 400 Bad Request — A required parameter is missing or a value fails validation.
• 401 Unauthorized — The Authorization header is absent or the key is not recognised.
• 403 Forbidden — The key does not hold the scope required for this endpoint.
• 404 Not Found — The requested resource does not exist within your organisation.
• 409 Conflict — A resource with a conflicting unique identifier already exists (e.g. email already provisioned).
• 429 Too Many Requests — The per-minute rate limit has been exceeded.
• 503 Service Unavailable — The service is temporarily unavailable; retry after a short back-off.