SCIM Directory Sync

SCIM directory sync connects an AISIX organization to your identity provider (IdP) so member accounts are created, updated, and deactivated by the directory instead of by hand. AISIX implements the SCIM 2.0 protocol (RFC 7643/7644), which Okta, Microsoft Entra ID, and other enterprise IdPs speak natively.

Directory sync is built for organizations that attribute gateway usage to many people — hundreds or thousands of members — without dashboard logins for each of them. Members provisioned this way are the same login-less members you can create directly: they own API keys, carry rate limits and budgets, and appear in usage reporting, but they cannot sign in to the dashboard.

The compliance-critical half is deprovisioning: when a person is deactivated or removed in the IdP, AISIX deactivates the member and disables every API key that member owns. The change propagates to the gateway data plane, so the credentials stop working at the gateway itself — not just in the dashboard.

Enable Directory Sync

1. Open Settings and find the Directory sync (SCIM) card.

2. Turn on Enable SCIM provisioning (organization admins and owners only).

3. Copy the SCIM base URL shown on the card, for example:

   https://<your-cp-api-host>/scim/v2

4. Select Generate SCIM token (organization owners only) and copy the plaintext value before leaving the page — it is shown exactly once.

Configure the SCIM connector in your IdP with the base URL and the token as the bearer credential. The token is an admin token with the exclusive scim scope: it can call only the SCIM endpoints and is rejected on every other Cloud Admin API route, so a leaked IdP credential cannot read or change gateway resources. To rotate it, generate a new token, update the IdP, and revoke the old one on the Admin tokens page.

How Users Map to Members

SCIM attribute	AISIX member field
userName / emails[].value	Email address (the identity key)
displayName or name	Display name
externalId	Stable IdP identifier, unique per organization
active	false deactivates the member and disables its API keys
groups	Team membership (read-only; managed through the Groups endpoints)

Creating a user whose email already belongs to a member of the organization returns a 409 uniqueness error. Members created in the dashboard stay dashboard-managed: they are visible to the IdP in list responses, but SCIM cannot modify, deactivate, or delete them — in particular, directory sync can never touch an organization owner.

Deleting a user over SCIM disables the member's API keys first, removes the member from every team, and then removes the membership. Usage history is preserved for reporting. The email becomes available again, so a later re-provision creates a fresh member.

Deactivate vs. Delete

• active: false keeps the member and its keys, but the keys are disabled at the gateway. Setting active: true again re-enables only the keys directory sync disabled — keys an operator disabled by hand stay disabled.
• DELETE removes the membership permanently. Keys stay disabled and keep their usage history.

Map Groups to Teams and Roles

SCIM groups sync to AISIX teams: pushing a group creates a team with the same name, and group membership changes add or remove team members.

Two settings on the Directory sync (SCIM) card control the role mapping:

• Default role — the organization role every synced member gets (member by default, or admin).
• Admin group — the name of one group whose members get the admin role. Members outside it get the default role.

Roles of directory-synced members are recomputed on every group change, including group renames. A role changed by hand in the dashboard is overwritten by the next sync — treat the directory as the source of truth for synced members.

Supported Endpoints

The SCIM surface lives under /scim/v2 and answers in application/scim+json:

Endpoint	Methods
/Users	GET (list, eq filters on userName, emails.value, externalId), POST
/Users/{id}	GET, PUT, PATCH, DELETE
/Groups	GET (list, eq filters on displayName, externalId), POST
/Groups/{id}	GET, PUT, PATCH, DELETE
/ServiceProviderConfig, /ResourceTypes, /Schemas	GET

PATCH follows the SCIM PatchOp shape, including the path forms Okta and Microsoft Entra ID emit (active, members[value eq "..."], and operations without a path). List responses page with startIndex and count (up to 200 per page). Attributes with no AISIX mapping — such as phone numbers or addresses — are accepted and ignored, so IdP attribute mappings do not need trimming.

Example: provision a user with curl:

curl -sS "https://<your-cp-api-host>/scim/v2/Users" \
  -H "Authorization: Bearer ${AISIX_SCIM_TOKEN}" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "dev@example.com",
    "displayName": "Developer One",
    "emails": [{ "value": "dev@example.com", "primary": true }]
  }'

Attribute Usage to Synced Members

Directory sync creates the members; attribution works the same as for any member:

1. Create or update an API key and set its owner to the synced member.
2. Usage, rate limits, and budgets attribute to that member.

When the IdP deactivates the person, the keys stop authenticating at the gateway within seconds.

Next Steps

• Members — the manual onboarding paths and how login-less members behave.
• Admin Tokens — scopes, rotation, and revocation for the SCIM token.
• Logging and Auditing — every SCIM mutation lands in the organization audit trail with the token owner as the actor.