Robots Center Agents Network
Log in Create workspace
Skip to content

API reference

SCIM v2

One tag: method, path, summary, auth, and scopes. Request and response fields ship in this page — expand a row to read the contract.

Browse docs

Endpoints

13
GET
/scim/v2/ServiceProviderConfig SCIM Token

Get SCIM service provider configuration

Description

Returns the SCIM 2.0 service provider configuration. Authenticate with `Authorization: Bearer` using a workspace SCIM token minted or revoked on Workspace admin (`/app/admin`) — not `/app/workspace`. This response advertises `filter.maxResults` 200. List endpoints do not honor that figure: `count` defaults to 50 and is capped at 100. `filter` is supported only on Users, and only for three `eq` expressions (see GET /scim/v2/Users). Groups ignore `filter`. Bulk, sort, ETag, and changePassword are not supported.

Auth

SCIM Token
Responses
200

Service provider configuration (advertised capabilities)

Returns: ServiceProviderConfig
Example
{
  "authenticationSchemes": [
    {
      "description": "Workspace SCIM bearer token",
      "name": "Bearer Token",
      "primary": true,
      "type": "oauthbearertoken"
    }
  ],
  "bulk": {
    "maxOperations": 0,
    "maxPayloadSize": 0,
    "supported": false
  },
  "changePassword": {
    "supported": false
  },
  "etag": {
    "supported": false
  },
  "filter": {
    "maxResults": 200,
    "supported": true
  },
  "patch": {
    "supported": true
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
  ],
  "sort": {
    "supported": false
  }
}
401

Invalid or missing SCIM token
GET
/scim/v2/Users SCIM Token

List SCIM users

Description

Lists SCIM-linked workspace members as a SCIM ListResponse. Pagination: `startIndex` is 1-based (default 1). `count` defaults to 50 and is capped at 100 (a requested 500 still returns at most 100). Filter is not generic SCIM. Only these exact `eq` forms are applied: `userName eq "…"`, `emails.value eq "…"`, and `externalId eq "…"`. Any other expression is ignored and the unfiltered page is returned.

Auth

SCIM Token
Parameters
Name In Type Required Description
startIndex query integer No 1-based index of the first result (default 1)
count query integer No Page size (default 50, maximum 100)
filter query string No Only `userName eq`, `emails.value eq`, and `externalId eq` are honored. Other filters are ignored.
Responses
200

Paginated user list

Returns: ScimUserList
Example
{
  "Resources": [
    {
      "active": true,
      "emails": [
        {
          "primary": true,
          "value": "[email protected]"
        }
      ],
      "externalId": "ext-user-001",
      "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635",
      "meta": {
        "created": "2026-01-15T10:00:00Z",
        "lastModified": "2026-03-27T09:00:00Z",
        "resourceType": "User"
      },
      "name": {
        "formatted": "Jane Admin"
      },
      "roles": [
        {
          "value": "admin"
        }
      ],
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "userName": "[email protected]"
    }
  ],
  "itemsPerPage": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "startIndex": 1,
  "totalResults": 1
}
401

Invalid or missing SCIM token
POST
/scim/v2/Users SCIM Token

Create or update SCIM user

Description

Upserts a user by `externalId` (idempotent) or email. `userName` is the email. `roles` is a list of `{value}` (or bare strings) in `owner` | `admin` | `member` | `auditor`; omitted roles default to `member`. Responses include the effective `roles` after group reconciliation. `409` `application/scim+json` is returned for uniqueness conflicts (`Resource already exists`) and last-owner protection (`Cannot modify the last workspace owner`).

Auth

SCIM Token
Request Body
Field Type Required Description
active boolean No Whether the membership is active (false deprovisions)
name object No User name object. `formatted` is the display name.
emails array<object> No User email addresses
schemas array<object> Yes SCIM schema URIs
externalId string No IdP external id. Used as the upsert idempotency key.
roles array<object> No Workspace roles. Each item is `{value}` or a string: owner, admin, member, or auditor. Default member.
userName string Yes User email address
Responses
200

User created or updated

Returns: ScimUser
Example
{
  "active": true,
  "emails": [
    {
      "primary": true,
      "value": "[email protected]"
    }
  ],
  "externalId": "ext-user-001",
  "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635",
  "meta": {
    "created": "2026-01-15T10:00:00Z",
    "lastModified": "2026-03-27T09:00:00Z",
    "resourceType": "User"
  },
  "name": {
    "formatted": "Jane Admin"
  },
  "roles": [
    {
      "value": "admin"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "[email protected]"
}
401

Invalid or missing SCIM token
409

SCIM Error: uniqueness conflict or last-owner protection (application/scim+json)
422

Invalid userName/email or user data
GET
/scim/v2/Users/:id SCIM Token

Get SCIM user

Description

Returns a provisioned user by user UUID. Non-UUID ids are 404.

Auth

SCIM Token
Parameters
Name In Type Required Description
id path string Yes User UUID
Responses
200

User details

Returns: ScimUser
Example
{
  "active": true,
  "emails": [
    {
      "primary": true,
      "value": "[email protected]"
    }
  ],
  "externalId": "ext-user-001",
  "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635",
  "meta": {
    "created": "2026-01-15T10:00:00Z",
    "lastModified": "2026-03-27T09:00:00Z",
    "resourceType": "User"
  },
  "name": {
    "formatted": "Jane Admin"
  },
  "roles": [
    {
      "value": "admin"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "[email protected]"
}
401

Invalid or missing SCIM token
404

User not found
PUT
/scim/v2/Users/:id SCIM Token

Update SCIM user

Description

Full replacement of a provisioned user. Accepts the same attributes as create, including `roles` (`owner` | `admin` | `member` | `auditor`) and `emails`. Last-owner demotion/deactivation and uniqueness conflicts are `409` application/scim+json.

Auth

SCIM Token
Request Body
Field Type Required Description
active boolean No Whether the membership is active
name object No User name object (`formatted`)
emails array<object> No User email addresses
schemas array<object> Yes SCIM schema URIs
externalId string No IdP external id
roles array<object> No Workspace roles (`owner` | `admin` | `member` | `auditor`). Default keeps the existing role when omitted on update.
userName string Yes User email address
Parameters
Name In Type Required Description
id path string Yes User UUID
Responses
200

User updated

Returns: ScimUser
Example
{
  "active": true,
  "emails": [
    {
      "primary": true,
      "value": "[email protected]"
    }
  ],
  "externalId": "ext-user-001",
  "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635",
  "meta": {
    "created": "2026-01-15T10:00:00Z",
    "lastModified": "2026-03-27T09:00:00Z",
    "resourceType": "User"
  },
  "name": {
    "formatted": "Jane Admin"
  },
  "roles": [
    {
      "value": "admin"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "[email protected]"
}
401

Invalid or missing SCIM token
404

User not found
409

SCIM Error: uniqueness conflict or last-owner protection (application/scim+json)
422

Invalid user data
PATCH
/scim/v2/Users/:id SCIM Token

Patch SCIM user

Description

SCIM PATCH. Honored `replace` paths: `active`, `name.formatted`, `userName`, and `roles`. A pathless `replace` may also set `active`, `userName`, `name`, `roles`, `emails`, and `externalId`. Other operations are ignored. Last-owner and uniqueness conflicts are `409` application/scim+json.

Auth

SCIM Token
Request Body
Field Type Required Description
schemas array<object> Yes SCIM schema URIs
Operations array<object> No PATCH operations. replace on active | name.formatted | userName | roles, or a pathless replace map.
Parameters
Name In Type Required Description
id path string Yes User UUID
Responses
200

User patched

Returns: ScimUser
Example
{
  "active": true,
  "emails": [
    {
      "primary": true,
      "value": "[email protected]"
    }
  ],
  "externalId": "ext-user-001",
  "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635",
  "meta": {
    "created": "2026-01-15T10:00:00Z",
    "lastModified": "2026-03-27T09:00:00Z",
    "resourceType": "User"
  },
  "name": {
    "formatted": "Jane Admin"
  },
  "roles": [
    {
      "value": "admin"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "[email protected]"
}
401

Invalid or missing SCIM token
404

User not found
409

SCIM Error: uniqueness conflict or last-owner protection (application/scim+json)
422

Invalid user data
DELETE
/scim/v2/Users/:id SCIM Token

Deactivate SCIM user

Description

Soft-deletes the membership (`status` disabled). Deactivating the last workspace owner is `409` `Cannot modify the last workspace owner` (`application/scim+json`). Already-disabled users succeed as 204.

Auth

SCIM Token
Parameters
Name In Type Required Description
id path string Yes User UUID
Responses
204

User deactivated
401

Invalid or missing SCIM token
404

User not found
409

Cannot modify the last workspace owner (application/scim+json)
GET
/scim/v2/Groups SCIM Token

List SCIM groups

Description

Lists provisioned groups stored on the workspace. Same pagination as Users: `startIndex` default 1, `count` default 50, maximum 100. There is no `filter` parameter — a supplied `filter` is ignored.

Auth

SCIM Token
Parameters
Name In Type Required Description
startIndex query integer No 1-based index of the first result (default 1)
count query integer No Page size (default 50, maximum 100)
Responses
200

Paginated group list

Returns: ScimGroupList
Example
{
  "Resources": [
    {
      "displayName": "Engineering",
      "externalId": "ext-group-eng",
      "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "members": [
        {
          "value": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
        }
      ],
      "meta": {
        "resourceType": "Group"
      },
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ]
    }
  ],
  "itemsPerPage": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "startIndex": 1,
  "totalResults": 1
}
401

Invalid or missing SCIM token
POST
/scim/v2/Groups SCIM Token

Create or update SCIM group

Description

Upserts a group by `externalId`. `members` is a list of user UUIDs (`{value}`). After write, membership roles are reconciled from each group's `displayName` tokens: - `admin` / `admins` / `administrator` / `administrators` → `admin` - `auditor` / `auditors` → `auditor` - names starting with `non-` / `not-` stay `member` - `owner` is never granted from a group name (`Workspace Owners` stays member) A user's effective role is the highest of their explicit SCIM `roles` and every matching group (owner > admin > auditor > member). The last workspace owner is never demoted by group sync. Uniqueness conflicts are `409` `Resource already exists`.

Auth

SCIM Token
Request Body
Field Type Required Description
members array<object> No Member user UUIDs (`{value}` or equivalent)
schemas array<object> Yes SCIM schema URIs
displayName string Yes Group display name. Tokens grant admin or auditor as described above; owner is never granted from the name.
externalId string No External group ID (upsert key)
Responses
200

Group created or updated

Returns: ScimGroup
Example
{
  "displayName": "Engineering",
  "externalId": "ext-group-eng",
  "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
  "members": [
    {
      "value": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
    }
  ],
  "meta": {
    "resourceType": "Group"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ]
}
401

Invalid or missing SCIM token
409

SCIM Error: Resource already exists (application/scim+json)
422

Invalid group data
GET
/scim/v2/Groups/:id SCIM Token

Get SCIM group

Description

Returns a provisioned group by id or externalId.

Auth

SCIM Token
Parameters
Name In Type Required Description
id path string Yes Group UUID or externalId
Responses
200

Group details

Returns: ScimGroup
Example
{
  "displayName": "Engineering",
  "externalId": "ext-group-eng",
  "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
  "members": [
    {
      "value": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
    }
  ],
  "meta": {
    "resourceType": "Group"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ]
}
401

Invalid or missing SCIM token
404

Group not found
PUT
/scim/v2/Groups/:id SCIM Token

Update SCIM group

Description

Replaces `displayName` and `members`, then reconciles workspace roles from displayName tokens (admin/auditor only; owner is never granted from a group name). Uniqueness conflicts are `409`.

Auth

SCIM Token
Request Body
Field Type Required Description
members array<object> No Member user UUIDs
schemas array<object> Yes SCIM schema URIs
displayName string Yes Group display name. Tokens grant admin or auditor; owner is never granted from the name.
Parameters
Name In Type Required Description
id path string Yes Group UUID
Responses
200

Group updated

Returns: ScimGroup
Example
{
  "displayName": "Engineering",
  "externalId": "ext-group-eng",
  "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
  "members": [
    {
      "value": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
    }
  ],
  "meta": {
    "resourceType": "Group"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ]
}
401

Invalid or missing SCIM token
404

Group not found
409

SCIM Error: Resource already exists (application/scim+json)
PATCH
/scim/v2/Groups/:id SCIM Token

Patch SCIM group

Description

Honored `replace` paths: `displayName` and `members`. Other operations are ignored. Role reconciliation from the new displayName is the same as create/update. Uniqueness conflicts are `409`.

Auth

SCIM Token
Request Body
Field Type Required Description
schemas array<object> Yes SCIM schema URIs
Operations array<object> No PATCH operations. replace on displayName or members.
Parameters
Name In Type Required Description
id path string Yes Group UUID
Responses
200

Group patched

Returns: ScimGroup
Example
{
  "displayName": "Engineering",
  "externalId": "ext-group-eng",
  "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
  "members": [
    {
      "value": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
    }
  ],
  "meta": {
    "resourceType": "Group"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ]
}
401

Invalid or missing SCIM token
404

Group not found
409

SCIM Error: Resource already exists (application/scim+json)
DELETE
/scim/v2/Groups/:id SCIM Token

Delete SCIM group

Description

Deletes a provisioned group and re-runs role reconciliation for remaining groups.

Auth

SCIM Token
Parameters
Name In Type Required Description
id path string Yes Group UUID
Responses
204

Group deleted
401

Invalid or missing SCIM token
404

Group not found