SCIM API Reference

This page covers the SCIM provisioning API that identity providers call, plus the portal-side token-management APIs that tenant admins use to manage SCIM access.

Two API Surfaces to Know

SCIM provisioning API

This is the standards-based surface your IdP calls:

/scim/v2

Portal token-management API

This is the authenticated portal surface your tenant admins use:

/api/v1/scim/tokens

Treat them as separate layers of the same capability.

Base URL

Use the base URL for your actual enterprise portal domain:

https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2

Authentication

Discovery endpoints

These endpoints are public in the current implementation:

• GET /scim/v2/ServiceProviderConfig
• GET /scim/v2/Schemas
• GET /scim/v2/Schemas/{id}
• GET /scim/v2/ResourceTypes
• GET /scim/v2/ResourceTypes/{name}

User and group endpoints

These require a SCIM bearer token:

Authorization: Bearer scim_your_token_here
Accept: application/scim+json
Content-Type: application/scim+json

If the token is missing, revoked, expired, or malformed, the middleware returns 401 Unauthorized with WWW-Authenticate: Bearer realm="SCIM".

Content Type

The SCIM endpoints return:

application/scim+json

Discovery Endpoints

Service provider configuration

GET /scim/v2/ServiceProviderConfig

Use this to verify capabilities before turning on full provisioning in an IdP.

The response advertises support for:

• patch operations
• filtering
• sorting
• ETags
• bearer-token authentication

Unsupported capabilities: bulk operations (Bulk.Supported: false) and change password (ChangePassword.Supported: false). Filter results are capped at MaxResults: 200.

Schemas

GET /scim/v2/Schemas
GET /scim/v2/Schemas/{id}

Use these when your IdP or provisioning tool needs to inspect supported schema definitions.

Resource types

GET /scim/v2/ResourceTypes
GET /scim/v2/ResourceTypes/{name}

The current implementation exposes SCIM resource types for:

• User
• Group

User Resource Endpoints

List users

GET /scim/v2/Users

Common query parameters:

• filter
• startIndex
• count
• sortBy
• sortOrder

Example:

curl -sS "https://YOUR_PORTAL_OR_ENTERPRISE_DOMAIN/scim/v2/Users?filter=userName%20eq%20%[email protected]%22" \
  -H 'Authorization: Bearer scim_your_token_here' \
  -H 'Accept: application/scim+json'

Create user

POST /scim/v2/Users

Typical request:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "[email protected]",
  "externalId": "idp-user-123",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true
}

On success, the handler returns:

• 201 Created
• a Location header pointing to the created user resource
• the SCIM user payload, including metadata such as resourceType, location, and version

Read, replace, patch, and delete users

GET    /scim/v2/Users/{id}
PUT    /scim/v2/Users/{id}
PATCH  /scim/v2/Users/{id}
DELETE /scim/v2/Users/{id}

Notes that matter operationally:

• GET returns the resource and emits an ETag header when metadata is available
• PUT expects the body id to match the URL if present
• PATCH supports SCIM patch operations
• DELETE returns 204 No Content

Group Resource Endpoints

List groups

GET /scim/v2/Groups

Like users, groups support filtering, pagination, and sorting parameters.

Pagination defaults to 100 results per page with a maximum of 200. Set the count parameter to control page size.

Create group

POST /scim/v2/Groups

Typical request:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "AxonFlow-Engineers",
  "externalId": "idp-group-456",
  "members": [
    { "value": "user-id-1" },
    { "value": "user-id-2" }
  ]
}

Read, replace, patch, and delete groups

GET    /scim/v2/Groups/{id}
PUT    /scim/v2/Groups/{id}
PATCH  /scim/v2/Groups/{id}
DELETE /scim/v2/Groups/{id}

Use group provisioning only after user provisioning is stable, especially if you plan to connect groups to AxonFlow role assignment workflows.

Token-Management Endpoints

These endpoints are not SCIM endpoints. They are portal-admin APIs used to manage SCIM credentials.

List tokens

GET /api/v1/scim/tokens

Returns metadata for the tenant's SCIM tokens, including:

• token ID
• token prefix
• token name
• creation time
• expiration time, if any
• last-used time, if any
• revoked state

Create token

POST /api/v1/scim/tokens

Current request shape:

{
  "name": "okta-production",
  "expires_in": 31536000
}

expires_in is optional and is expressed in seconds. If it is omitted, the token does not expire automatically.

The response includes:

• token metadata
• the plaintext token value

Store that value immediately. It is the one-time secret your IdP will use.

Revoke token

DELETE /api/v1/scim/tokens/{tokenID}

Successful revocation returns:

204 No Content

Group-to-Role Mapping

AxonFlow stores synced groups and supports mapping them to AxonFlow roles as part of the enterprise access model.

Treat group-to-role mapping primarily as an admin workflow rather than a direct IdP provisioning concern, because the most important part for customers is:

• groups arrive cleanly through SCIM
• roles exist in the tenant
• tenant admins can align synced groups to those roles in a controlled way

Use Group to Role Mapping for the recommended workflow and rollout pattern.

Common Status Codes

Status	Meaning
200	successful read or update
201	resource created
204	delete or revoke succeeded
400	invalid JSON, invalid syntax, or invalid value
401	missing, revoked, expired, or invalid token
404	resource not found
409	duplicate or conflicting identity data
412	ETag version mismatch or concurrent update conflict
500	server or database error

Practical Validation Sequence

When integrating a new IdP, verify the APIs in this order:

1. GET /scim/v2/ServiceProviderConfig
2. GET /scim/v2/Users with a SCIM token
3. POST /scim/v2/Users from the IdP test flow
4. PATCH or PUT user updates
5. deactivation or delete behavior
6. group provisioning
7. token rotation through /api/v1/scim/tokens

Related Docs

• SCIM Overview
• SCIM Getting Started
• Group to Role Mapping
• SCIM Troubleshooting