SCIM Directory Sync

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

Directory sync is built for organizations that attribute gateway usage to many people, including 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. They cannot sign in to the dashboard.

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 only 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 AISIX Cloud Admin API route, so a leaked IdP credential cannot read or change gateway resources.

To rotate the credential, generate a new SCIM token, update the IdP connector, and revoke the old token 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. Directory sync can never modify 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 that 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.

The Directory sync (SCIM) card controls the role mapping:

• Default role: the organization role a synced member gets when they belong to no mapped group — member, admin, or a custom role.
• Group → role mappings: each mapping assigns a role to the members of one directory group, matched by group display name. Any assignable role works as a target, including custom roles. When a member belongs to several mapped groups, an admin mapping wins; otherwise the mapping whose group name sorts first applies.

Roles of directory-synced members are recomputed on every group change, including group renames, and whenever the mappings or the default role change. A role changed by hand in the dashboard is overwritten by the next sync, so treat the directory as the source of truth for synced members. Directory sync can never assign the owner role.

Use Synced Members for Attribution

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 are attributed to that member.

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

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
      }
    ]
  }'

Next Steps

• Members: 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.