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.

What a provisioned user becomes depends on whether AISIX trusts the organization's identity provider for the user's email address, the same decision that single sign-on makes. An On-Premises control plane trusts it for every address. The SaaS service trusts it only for addresses on the organization's verified domains.

• A trusted address becomes a member at once. When the email is new to AISIX, directory sync creates a login-less member, like one an On-Premises administrator can create directly: it owns API keys, carries rate limits and budgets, and appears in usage reporting, but cannot sign in to the dashboard until an administrator enables sign-in for it, or the person connects it through SSO. When the email already belongs to an AISIX account that is not yet a member of this organization, directory sync attaches the new membership to that account instead, so the person can sign in with the account's existing credentials. On the SaaS service, an account that was registered for the address but never verified it is taken over: it loses its password, its sessions, its pending email verification links, and its SSO links. It takes the name a new account would get from the request, displayName or name, falling back to the email address, its acceptance of the User Agreement and Privacy Policy is cleared, and its email address is marked verified. The takeover is recorded as a verified_domain_claim audit entry; see Audit Records.
• Any other address becomes a member waiting to join. No account is created or attached. AISIX invites the address, and the person joins by accepting the invitation or by connecting the organization's SSO. See Members Waiting to Join.

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.

Export the values when you want to test the SCIM endpoints from the shell:

export AISIX_SCIM_BASE_URL="https://<your-cp-api-host>/scim/v2"
export AISIX_SCIM_TOKEN="YOUR_SCIM_TOKEN"

Configure the SCIM connector in your IdP with the same base URL and 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 of an account that directory sync creates
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)

SCIM responses return the userName, name, displayName, and emails that the IdP sent, along with the AISIX id, externalId, active, and groups. They never return the name or email address of the AISIX account, so they do not reveal whether an address already has an account. A member that directory sync did not create, or created before the control plane stored the IdP's values, returns the account's stored email address and name instead.

SCIM changes the name and email address of the account behind a member only when the account has no password and belongs to no other organization. On the SaaS service, it also requires the new email address to be on one of the verified domains. Otherwise, the account keeps its name and address, AISIX stores the IdP's new values, and responses return them.

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.

What a Deactivated Member Loses

A deactivated member keeps its membership record and role, but loses access to the organization, including through a dashboard session or a personal access token:

• The organization no longer appears in GET /api/orgs, and the organization's routes return 403 with the error code NOT_A_MEMBER.
• An API key cannot be bound to the member. Creating a key with the member's user_id, or changing an existing key's user_id to that member, returns 400 with the error code INVALID_REQUEST. Editing a key that is already bound to the member without changing its user_id still works.
• A key whose owner is deactivated cannot be re-enabled. Setting disabled to false returns 400 with the error code INVALID_REQUEST. To hand the key to someone else, bind it to an active member or remove its user_id in the same request that enables it. That transfer is allowed on purpose.
• An invitation to the organization cannot restore access. Redeeming one returns 403 with the error code MEMBER_DEACTIVATED, the invitation stays pending, and the membership stays deactivated. Reactivate the member from the identity provider instead.
• Unused set-password links the organization issued for the member stop working. Deleting the member through SCIM retires them too.
• No new set-password link can be issued while the member is deactivated: POST /members/{user_id}/set_password_link returns 400 with the error code INVALID_REQUEST, and the Members list offers no sign-in actions for the member.

Members Waiting to Join

On the SaaS service, a user provisioned at an address outside the organization's verified domains is recorded as a member waiting to join. It has an id the IdP can use like any other user's, but no account is created or attached to it until the person joins.

AISIX sends an invitation to the address, in the name of the owner of the SCIM token:

• The emails count toward the organization's hourly invitation email limit, which for directory sync is counted per organization. Over the limit, the invitation is still created without an email, and an administrator can resend it from the Pending invitations tab.
• When the address already has a pending invitation, for example one an administrator sent from the dashboard, that invitation is used and no new email is sent. Directory sync never revokes an invitation it did not create.
• A user provisioned with active: false gets no invitation until the IdP sets active: true.

The member joins, and becomes a regular member with the same SCIM id, in either of these ways:

• The person accepts the invitation signed in to an account that uses the same email address. An invitation to that address that an administrator issued again, after the directory's own expired or was revoked, works as well.
• The person connects the organization's SSO on the Connect page, and the NameID of their identity equals the externalId the directory sent. Configure the IdP to send the same identifier as both.

Either way, the member joins with the role, externalId, IdP attributes, and team memberships the directory gave it, and an unused invitation that directory sync sent is revoked. If the account is a member of the organization already, the existing membership is kept, and the waiting member is removed.

Until then, changes from the IdP apply to the waiting member only:

• active: false keeps the waiting member and its id, and revokes its invitation. active: true invites it again.
• Changing its email address revokes the invitation to the old address and, for an active member, invites the new one. The new address must not belong to another SCIM user of the organization.
• DELETE removes the waiting member and revokes the invitation that directory sync sent.

GET /Users lists waiting members alongside regular ones, filters included, and groups can reference them. They are listed in the Waiting to join section of the Members page, and by the GET /pending_members operation of the AISIX Cloud Admin API, which takes the same page and page_size parameters as GET /members. An organization that wants directory sync to provision members directly verifies its domains first.

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, and it leaves alone a role that SSO role mapping wrote.

Combine with Single Sign-On

Directory sync does not sign anyone in. To let synced members sign in to the dashboard through the same IdP, configure single sign-on. Send the same identifier as the SCIM externalId and the SAML NameID, so that a member waiting to join is activated when the person connects SSO. A synced member who signs in through SSO stays managed by directory sync, except that a role written by SSO role mapping rules is not overwritten by the group-to-role mappings.

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 and budgets are attributed to that member, and member-scoped rate limit policies apply.

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 "${AISIX_SCIM_BASE_URL}/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

Continue with Connect an AISIX Gateway to attach a gateway to an environment. To investigate directory-driven changes later, use Logging and Auditing.