SCIM 2.0 Endpoints

Provision and deprovision users and groups from an external directory such as Okta or Azure AD using the SCIM 2.0 protocol (RFC 7642–7644).

Authentication

All SCIM endpoints require a per-tenant SCIM bearer token.

Authorization: Bearer <scim-token>

Obtain your SCIM token from the Settings → Directory Sync page in the Bulwark dashboard, or via the Admin API. The base URL for all SCIM requests is:

https://api.bulwarkauth.com/scim/v2

Service Provider Configuration

GET /scim/v2/ServiceProviderConfig

Returns the SCIM capabilities supported by Bulwark. Used by IdPs during initial setup.

Response 200

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "documentationUri": "https://docs.bulwarkauth.com/api/scim",
  "patch": { "supported": true },
  "bulk": { "supported": false },
  "filter": { "supported": true, "maxResults": 200 },
  "changePassword": { "supported": true },
  "sort": { "supported": false },
  "etag": { "supported": false },
  "authenticationSchemes": [
    {
      "type": "oauthbearertoken",
      "name": "OAuth Bearer Token",
      "description": "Per-tenant SCIM token issued by Bulwark"
    }
  ]
}

Schemas

GET /scim/v2/Schemas

Returns all supported SCIM schema definitions.

GET /scim/v2/Schemas/{id}

Returns a single schema by URN (e.g. urn:ietf:params:scim:schemas:core:2.0:User).

Resource Types

GET /scim/v2/ResourceTypes

Returns the User and Group resource type definitions.

Users

Create User

POST /scim/v2/Users

Body

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

Response 201

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "usr_01j...",
  "externalId": "okta-user-00u...",
  "userName": "[email protected]",
  "name": { "givenName": "Jane", "familyName": "Doe" },
  "emails": [{ "value": "[email protected]", "primary": true }],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2026-03-30T00:00:00Z",
    "lastModified": "2026-03-30T00:00:00Z",
    "location": "https://api.bulwarkauth.com/scim/v2/Users/usr_01j..."
  }
}

Get User

GET /scim/v2/Users/{id}

Returns a single user by Bulwark ID or externalId.

List Users

GET /scim/v2/Users

Query Parameters

| Parameter | Description | |-----------|-------------| | filter | SCIM filter expression (e.g. userName eq "[email protected]") | | startIndex | 1-based pagination offset (default: 1) | | count | Page size (default: 20, max: 200) |

Response 200

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 42,
  "startIndex": 1,
  "itemsPerPage": 20,
  "Resources": [
    {
      "id": "usr_01j...",
      "userName": "[email protected]",
      "active": true
    }
  ]
}

Replace User

PUT /scim/v2/Users/{id}

Full replacement of all user attributes. The body must contain the complete user representation.

Response 200

Returns the full updated user resource.

Update User

PATCH /scim/v2/Users/{id}

Partial update using SCIM patch operations.

Body

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false }
  ]
}

Setting active to false deactivates the user and revokes all active sessions.

Response 200

Returns the full updated user resource.

Delete User

DELETE /scim/v2/Users/{id}

Permanently deprovisions the user. All sessions and tokens are revoked.

Response 204

No content.

Groups

Create Group

POST /scim/v2/Groups

Body

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "externalId": "grp-eng-001",
  "members": [
    { "value": "usr_01j...", "display": "Jane Doe" }
  ]
}

Response 201

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "grp_01j...",
  "displayName": "Engineering",
  "externalId": "grp-eng-001",
  "members": [{ "value": "usr_01j...", "display": "Jane Doe" }],
  "meta": {
    "resourceType": "Group",
    "created": "2026-03-30T00:00:00Z",
    "location": "https://api.bulwarkauth.com/scim/v2/Groups/grp_01j..."
  }
}

Get Group

GET /scim/v2/Groups/{id}

List Groups

GET /scim/v2/Groups

Supports the same filter, startIndex, and count parameters as List Users.

Replace Group

PUT /scim/v2/Groups/{id}

Full replacement of the group including its member list.

Update Group

PATCH /scim/v2/Groups/{id}

Add or remove members using SCIM patch operations.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [{ "value": "usr_01j_new..." }]
    },
    {
      "op": "remove",
      "path": "members[value eq \"usr_01j_old...\"]"
    }
  ]
}

Delete Group

DELETE /scim/v2/Groups/{id}

Removes the group. Members are not deleted.

Response 204

No content.