Directory Sync
Directory Sync
Directory Sync keeps your app's users and groups in step with your customer's directory. When their IT admin adds, updates or removes someone, OrbitID receives the change and forwards it to you as a webhook. You can also query the synced users and groups with the API.
With your coding agent
Claude Code, Cursor or Codex makes the change in your repo and tells you what it touched.
Sync our customers' directories into this app with OrbitID. Follow https://orbitid.com/docs/directory-sync.md 1. Add POST /webhooks/orbitid and verify OrbitID-Signature with ORBITID_WEBHOOK_SECRET. 2. Map each event's tenant to our organization. Create users on user.created, update them on user.updated, deactivate them on user.deleted or active: false. Never hard-delete. 3. If this app has teams or roles, mirror groups and memberships from the group.* events. 4. Make every handler idempotent and return 200 fast; the body can be an array of events. 5. Run the tests, then list what you changed and which events you ignore.
Supported directories
| Directory | How it connects |
|---|---|
| Okta | SCIM 2.0 |
| Microsoft Entra ID | SCIM 2.0 |
| OneLogin | SCIM 2.0 |
| JumpCloud | SCIM 2.0 |
| Any SCIM 2.0 directory | SCIM 2.0 |
| Google Workspace | OAuth (OrbitID polls the Google Directory API) |
Create a directory
In the dashboard open the environment, go to Directory Sync and click New directory. Choose the provider, enter the tenant it belongs to and, optionally, a webhook URL and secret. For SCIM providers the dashboard then shows:
- the SCIM endpoint:
https://app.orbitid.com/api/scim/v2.0/<directoryId> - a bearer token that the directory uses to authenticate. It is shown once, so copy it into the identity provider straight away.
Give both values to your customer's IT admin, or follow the provider guide together. For Google Workspace there is no SCIM endpoint: click Connect and sign in with a Google Workspace admin account instead.
One directory counts as one connection for billing.
Events
OrbitID emits these events as the directory changes:
| Event | When |
|---|---|
user.created | A user was provisioned |
user.updated | A user's attributes changed, including activation and deactivation |
user.deleted | A user was removed |
group.created | A group was pushed |
group.updated | A group was renamed or changed |
group.deleted | A group was removed |
group.user_added | A user was added to a group |
group.user_removed | A user was removed from a group |
Each event is delivered to the directory's webhook, signed with the directory's secret in the OrbitID-Signature header. Payloads and verification are described in Webhooks. Turn on Log webhook events on the directory to see every delivery and its response in the dashboard.
Query synced data
Use an API key to read what has been synced:
curl "https://app.orbitid.com/api/v1/dsync/users?tenant=acme&directoryId=<directoryId>" \-H "Authorization: Bearer orb_live_..."
GET /api/v1/dsync– list directories;GET /api/v1/dsync/<directoryId>– one directory.GET /api/v1/dsync/usersandGET /api/v1/dsync/users/<userId>– synced users.GET /api/v1/dsync/groups,GET /api/v1/dsync/groups/<groupId>and.../members– synced groups.GET /api/v1/dsync/eventsandGET /api/v1/dsync/events/<eventId>– webhook event log.
