Skip to main content

​
SCIM 2.0 provisioning

SCIM 2.0 (RFC 7643/7644) is the standard protocol identity providers use to create, update, and deactivate users in a downstream application. Connect your IdP — Okta, Microsoft Entra ID (formerly Azure AD), OneLogin, or any SCIM 2.0 client — and team membership in Orbit follows your directory: add a person to the Orbit app in your IdP and they get an Orbit seat; remove them and access is revoked. Use SCIM when you want the lifecycle of a user automated. It pairs with — but does not require — SAML SSO: SAML controls how users sign in, SCIM controls which users exist. Both are per-organization settings you opt into; neither is required to use Orbit, and SCIM stays off until an owner enables it.

​
Base URL and organization slug

Every SCIM endpoint is keyed by your organization slug:
Find your slug under Settings → Organization in the dashboard. The same value is rendered for you as a fully qualified Base URL on Settings → SCIM — paste that into your IdP as-is. These endpoints live at the API root, not under /api/v1.

​
Authentication

Your IdP authenticates with a Bearer token it sends on every request. Orbit answers with application/scim+json bodies and the SCIM error envelope (urn:ietf:params:scim:api:messages:2.0:Error), so IdPs can parse failure modes they expect. Generate the token under Settings → SCIM → Generate Bearer Token (owner-only), or via the API:
The plaintext token is returned once — only its hash is stored afterwards — so copy it into your IdP immediately. Rotating the token invalidates the previous one, so update the IdP right away. A missing or wrong token gets a 401 with SCIM type invalidCredentials. SCIM requests are rate-limited to 30 per minute per token. IdP syncs batch well under that; if you script provisioning yourself, page with count (max 500) rather than hammering the list endpoint.

​
Supported resources

Deletions are safe to re-run: deprovisioning a user revokes their active sessions, and removing an AI agent identity suspends it rather than deleting its configuration. User payloads accept the standard schema (userName, name, displayName, emails, active, externalId); extra attributes your IdP sends (locale, timezone, addresses) are accepted and ignored, so Okta and Entra payloads provision without attribute-trimming.

​
Role mapping

Which Orbit role a synced user lands in is your configuration, set under Settings → SCIM or with PATCH /api/v1/settings/scim:
  • defaultRole — the role for users provisioned without a group mapping (owner, admin, developer, billing, or viewer). viewer is the safe starting floor.
  • groupMapping — a map of IdP group name → Orbit role, applied on each sync.
Treat the group mapping as a privilege vector: a mapping like "Orbit Admins" → "owner" makes every member of that IdP group an owner on next sync. Both settings are owner-only.

​
Health and IdP detection

Check whether your IdP is actually talking to Orbit with:
The response reports an authenticationStatus (not_configured, no_requests_yet, authenticating, or auth_failing), the last request/success/failure timestamps, provisioning activity counts (users created, updated, deactivated, failed), and a best-effort detectedIdp inferred from the caller’s User-Agent (Okta, Microsoft Entra ID, OneLogin, …). Run Test connection on the Settings → SCIM page before enabling provisioning — it verifies the token exists, the Base URL resolves, and the discovery documents build, and the result shows up as the last test on the health endpoint.

​
Okta setup

  1. In Okta, add an application with SCIM 2.0 provisioning (or enable provisioning on your existing Orbit app).
  2. Under Provisioning → Configure Connection, set the SCIM connector base URL to https://api.orbit.devotel.io/scim/v2/{orgSlug} and choose HTTP Header auth with the Bearer token from Orbit.
  3. Test the connector configuration, then enable Create Users, Update User Attributes, and Deactivate Users under To App.
  4. Assign people (or groups, if you push groups) and confirm the first sync on the health endpoint above.

​
Microsoft Entra ID (Azure AD) setup

  1. In Entra, create or open your enterprise application, and go to Provisioning.
  2. Set Provisioning Mode to Automatic, then under Admin Credentials set Tenant URL to https://api.orbit.devotel.io/scim/v2/{orgSlug} and Secret Token to your Bearer token.
  3. Click Test Connection, save, and scope the users/groups you want to sync.
  4. Start provisioning and verify with the health endpoint.

​
Generic SCIM client

Any RFC 7643/7644-compliant client works. Create a user directly to verify the connection:
A 201 returns the full User resource with its assigned id. A 400 with invalidValue means a required field is missing or malformed; 401 means the token; 404 means the slug.

​
Scope and posture

SCIM provisioning is a tenant-owned control: you decide whether to use it, which IdP to trust, and which roles synced users receive. Orbit provides the endpoint and the audit trail — every IdP-driven create, update, and deprovision is recorded in your organization’s audit log — but enabling SCIM is never a platform requirement, and organizations without an IdP can manage seats manually under Settings → Team indefinitely.

​
See also