Directory (SCIM & LDAP)

Provision and de-provision users and groups via SCIM 2.0, manage SCIM bearer tokens, and configure outbound LDAP directory sync.

POST/directory/scim/:orgId/tokenGenerate SCIM tokenBearer Token▾

Creates a new SCIM bearer token for the organization. The token is returned once in plain text and stored as a SHA-256 hash. Requires SUPER_ADMIN, ORG_ADMIN, or API_ACCESS_MANAGEMENT_ADMIN role.

Parameters

Name	Type	Required	Description
`orgId`	string (UUID)	Required	Unique identifier of the organization.e.g. `b3e1f7a2-4c5d-6e8f-9a0b-1c2d3e4f5a6b`

Response Fields

Name	Type	Required	Description
`token`	string	Optional	The plain-text SCIM bearer token. Store it securely -- it cannot be retrieved again.

Response Example

{
  "token": "st_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"
}

Code Examples

curl -X POST "https://api.sutraid.com/directory/scim/b3e1f7a2-4c5d-6e8f-9a0b-1c2d3e4f5a6b/token" \
  -H "Authorization: Bearer <your_token>"

GET/directory/ldap/:orgId/configGet LDAP configurationBearer Token▾

Returns the current LDAP directory configuration for the organization, including connection details and sync filters. Returns null if no LDAP config exists.

Parameters

Name	Type	Required	Description
`orgId`	string (UUID)	Required	Unique identifier of the organization.e.g. `b3e1f7a2-4c5d-6e8f-9a0b-1c2d3e4f5a6b`

Response Fields

Name	Type	Required	Description
`enabled`	boolean	Optional	Whether LDAP sync is currently enabled.
`url`	string	Optional	LDAP server URL (e.g. ldaps://ldap.example.com:636).
`baseDn`	string	Optional	Base distinguished name for directory searches.
`bindDn`	string	Optional	Bind distinguished name used for authentication.
`bindPassword`	string	Optional	Password for the bind DN (masked in responses).
`userFilter`	string	Optional	LDAP filter for user entries.
`groupFilter`	string	Optional	LDAP filter for group entries.
`lastSyncAt`	string \| null	Optional	ISO 8601 timestamp of the last successful sync, or null if never synced.

Response Example

{
  "enabled": true,
  "url": "ldaps://ldap.example.com:636",
  "baseDn": "dc=example,dc=com",
  "bindDn": "cn=admin,dc=example,dc=com",
  "bindPassword": "********",
  "userFilter": "(objectClass=user)",
  "groupFilter": "(objectClass=group)",
  "lastSyncAt": "2024-06-15T14:30:00Z"
}

Code Examples

curl -X GET "https://api.sutraid.com/directory/ldap/b3e1f7a2-4c5d-6e8f-9a0b-1c2d3e4f5a6b/config" \
  -H "Authorization: Bearer <your_token>"

POST/directory/ldap/:orgId/configCreate or update LDAP configurationBearer Token▾

Creates or updates the LDAP directory configuration for the organization. Requires SUPER_ADMIN or ORG_ADMIN role. Uses an upsert strategy -- existing configs are merged.

Parameters

Name	Type	Required	Description
`orgId`	string (UUID)	Required	Unique identifier of the organization.e.g. `b3e1f7a2-4c5d-6e8f-9a0b-1c2d3e4f5a6b`

Request Body

Name	Type	Required	Description
`enabled`	boolean	Optional	Whether LDAP sync should be enabled. Defaults to true.e.g. `true`
`ldapUrl`	string	Required	LDAP server URL (e.g. ldaps://ldap.example.com:636). Also accepts "url" alias.e.g. `ldaps://ldap.example.com:636`
`ldapBaseDn`	string	Required	Base DN for directory searches. Also accepts "baseDn" alias.e.g. `dc=example,dc=com`
`ldapBindDn`	string	Required	Bind DN for LDAP authentication. Also accepts "bindDn" alias.e.g. `cn=admin,dc=example,dc=com`
`ldapBindPassword`	string	Required	Password for the bind DN. Also accepts "bindPassword" alias.e.g. `supersecret`
`ldapUserFilter`	string	Optional	LDAP search filter for user entries. Defaults to (objectClass=user). Also accepts "userFilter" alias.e.g. `(objectClass=user)`
`ldapGroupFilter`	string	Optional	LDAP search filter for group entries. Defaults to (objectClass=group). Also accepts "groupFilter" alias.e.g. `(objectClass=group)`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	Unique identifier of the directory config record.
`organizationId`	string	Optional	Organization the config belongs to.
`type`	string	Optional	Directory type. Always "LDAP" for this endpoint.
`enabled`	boolean	Optional	Whether LDAP sync is enabled.
`ldapUrl`	string	Optional	LDAP server URL.
`ldapBaseDn`	string	Optional	Base DN for searches.
`ldapBindDn`	string	Optional	Bind DN for authentication.
`ldapUserFilter`	string	Optional	User search filter.
`ldapGroupFilter`	string	Optional	Group search filter.
`lastSyncAt`	string \| null	Optional	ISO 8601 timestamp of last sync.

Response Example

{
  "id": "dc_01hx9z1q2w3e4r5t6y7u",
  "organizationId": "b3e1f7a2-4c5d-6e8f-9a0b-1c2d3e4f5a6b",
  "type": "LDAP",
  "enabled": true,
  "ldapUrl": "ldaps://ldap.example.com:636",
  "ldapBaseDn": "dc=example,dc=com",
  "ldapBindDn": "cn=admin,dc=example,dc=com",
  "ldapUserFilter": "(objectClass=user)",
  "ldapGroupFilter": "(objectClass=group)",
  "lastSyncAt": null
}

Code Examples

curl -X POST "https://api.sutraid.com/directory/ldap/b3e1f7a2-4c5d-6e8f-9a0b-1c2d3e4f5a6b/config" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ldapUrl": "ldaps://ldap.example.com:636",
    "ldapBaseDn": "dc=example,dc=com",
    "ldapBindDn": "cn=admin,dc=example,dc=com",
    "ldapBindPassword": "supersecret",
    "ldapUserFilter": "(objectClass=user)",
    "ldapGroupFilter": "(objectClass=group)"
  }'

POST/directory/ldap/:orgId/syncTrigger LDAP syncBearer Token▾

Initiates an outbound LDAP sync for the organization. Connects to the configured LDAP server, imports users and groups, and updates the lastSyncAt timestamp. Requires SUPER_ADMIN or ORG_ADMIN role.

Parameters

Name	Type	Required	Description
`orgId`	string (UUID)	Required	Unique identifier of the organization.e.g. `b3e1f7a2-4c5d-6e8f-9a0b-1c2d3e4f5a6b`

Response Fields

Name	Type	Required	Description
`status`	string	Optional	Confirmation message indicating the sync has been initiated.

Response Example

{
  "status": "Sync initiated"
}

Code Examples

curl -X POST "https://api.sutraid.com/directory/ldap/b3e1f7a2-4c5d-6e8f-9a0b-1c2d3e4f5a6b/sync" \
  -H "Authorization: Bearer <your_token>"

GET/scim/v2/:orgRef/ServiceProviderConfigGet SCIM service provider configurationSCIM Token▾

Returns the SCIM 2.0 service provider configuration describing supported features such as patch, filter, sort, and authentication schemes.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM schema URN for ServiceProviderConfig.
`patch.supported`	boolean	Optional	Whether PATCH operations are supported.
`bulk.supported`	boolean	Optional	Whether bulk operations are supported.
`filter.supported`	boolean	Optional	Whether filtering is supported.
`filter.maxResults`	number	Optional	Maximum results returned by a filter query.
`changePassword.supported`	boolean	Optional	Whether password changes are supported.
`sort.supported`	boolean	Optional	Whether sorting is supported.
`etag.supported`	boolean	Optional	Whether ETags are supported.
`authenticationSchemes`	object[]	Optional	List of supported authentication schemes.

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
  ],
  "patch": {
    "supported": true
  },
  "bulk": {
    "supported": false,
    "maxOperations": 0,
    "maxPayloadSize": 0
  },
  "filter": {
    "supported": true,
    "maxResults": 200
  },
  "changePassword": {
    "supported": false
  },
  "sort": {
    "supported": true
  },
  "etag": {
    "supported": false
  },
  "authenticationSchemes": [
    {
      "type": "oauthbearertoken",
      "name": "Bearer Token",
      "description": "Use SCIM bearer token in Authorization header",
      "specUri": "https://datatracker.ietf.org/doc/html/rfc6750",
      "primary": true
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/scim/v2/my-org/ServiceProviderConfig" \
  -H "Authorization: Bearer <scim_token>"

GET/scim/v2/:orgRef/SchemasGet SCIM schemasSCIM Token▾

Returns the list of SCIM resource schemas supported by this service provider (User and Group).

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM ListResponse schema URN.
`totalResults`	number	Optional	Total number of schema resources returned.
`Resources`	object[]	Optional	Array of schema definitions (User, Group).
`Resources[].id`	string	Optional	Schema URN identifier.
`Resources[].name`	string	Optional	Human-readable schema name.
`Resources[].description`	string	Optional	Description of the schema.

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 2,
  "Resources": [
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:User",
      "name": "User",
      "description": "User Account"
    },
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "name": "Group",
      "description": "Group"
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/scim/v2/my-org/Schemas" \
  -H "Authorization: Bearer <scim_token>"

GET/scim/v2/:orgRef/ResourceTypesGet SCIM resource typesSCIM Token▾

Returns the list of SCIM resource types supported by this service provider, including their endpoints and schema URNs.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM ListResponse schema URN.
`totalResults`	number	Optional	Total number of resource types returned.
`Resources`	object[]	Optional	Array of resource type definitions.
`Resources[].id`	string	Optional	Resource type identifier (User or Group).
`Resources[].name`	string	Optional	Human-readable resource type name.
`Resources[].endpoint`	string	Optional	Relative endpoint path for this resource type.
`Resources[].schema`	string	Optional	Schema URN for this resource type.

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 2,
  "Resources": [
    {
      "id": "User",
      "name": "User",
      "endpoint": "/Users",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User"
    },
    {
      "id": "Group",
      "name": "Group",
      "endpoint": "/Groups",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:Group"
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/scim/v2/my-org/ResourceTypes" \
  -H "Authorization: Bearer <scim_token>"

GET/scim/v2/:orgRef/UsersList SCIM usersSCIM Token▾

Returns a paginated SCIM 2.0 ListResponse of user resources for the organization. Supports filtering by userName, externalId, or id.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`
`filter`	string	Optional	SCIM filter expression. Supports userName eq, externalId eq, and id eq.e.g. `userName eq "jane@example.com"`
`startIndex`	number	Optional	1-based index of the first result. Defaults to 1.e.g. `1`
`count`	number	Optional	Maximum number of results per page. Defaults to 100, maximum 200.e.g. `100`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM ListResponse schema URN.
`totalResults`	number	Optional	Total number of user resources matching the query.
`startIndex`	number	Optional	The 1-based index of the first result in the current set.
`itemsPerPage`	number	Optional	Number of resources returned in this response.
`Resources`	User[]	Optional	Array of SCIM User resources.
`Resources[].schemas`	string[]	Optional	SCIM User schema URN.
`Resources[].id`	string	Optional	SutraID user identifier.
`Resources[].userName`	string	Optional	Email address of the user.
`Resources[].externalId`	string	Optional	External identifier from the identity provider.
`Resources[].name`	object	Optional	Name object with givenName and familyName.
`Resources[].emails`	object[]	Optional	Array of email objects.
`Resources[].active`	boolean	Optional	Whether the user account is active.

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 2,
  "startIndex": 1,
  "itemsPerPage": 2,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "userName": "jane@example.com",
      "externalId": "ext-001",
      "name": {
        "givenName": "Jane",
        "familyName": "Doe"
      },
      "emails": [
        {
          "value": "jane@example.com",
          "primary": true,
          "type": "work"
        }
      ],
      "active": true
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/scim/v2/my-org/Users?startIndex=1&count=100" \
  -H "Authorization: Bearer <scim_token>"

GET/scim/v2/:orgRef/Users/:userIdGet SCIM user by IDSCIM Token▾

Returns a single SCIM 2.0 User resource by its SutraID user identifier. The user must be a member of the specified organization.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`
`userId`	string (UUID)	Required	SutraID user identifier.e.g. `a1b2c3d4-e5f6-7890-abcd-ef1234567890`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM User schema URN.
`id`	string	Optional	SutraID user identifier.
`userName`	string	Optional	Email address of the user.
`externalId`	string	Optional	External identifier from the identity provider.
`name`	object	Optional	Name object with givenName and familyName.
`emails`	object[]	Optional	Array of email objects.
`active`	boolean	Optional	Whether the user account is active.

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userName": "jane@example.com",
  "externalId": "ext-001",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "jane@example.com",
      "primary": true,
      "type": "work"
    }
  ],
  "active": true
}

Code Examples

curl -X GET "https://api.sutraid.com/scim/v2/my-org/Users/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <scim_token>"

POST/scim/v2/:orgRef/UsersCreate SCIM userSCIM Token▾

Provisions a new user via SCIM 2.0. If a user with the same email already exists, their profile is updated and they are added to the organization. Returns 201 on success.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`

Request Body

Name	Type	Required	Description
`userName`	string	Required	Email address of the user. Can also be provided as emails[0].value.e.g. `jane@example.com`
`externalId`	string	Optional	External identifier from the upstream identity provider.e.g. `ext-001`
`name`	object	Optional	Name object containing givenName and familyName.e.g. `{ "givenName": "Jane", "familyName": "Doe" }`
`emails`	object[]	Optional	Array of email objects. The first entry with a value is used if userName is not set.e.g. `[{ "value": "jane@example.com", "primary": true, "type": "work" }]`
`active`	boolean	Optional	Whether the user should be active. Defaults to true.e.g. `true`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM User schema URN.
`id`	string	Optional	SutraID user identifier.
`userName`	string	Optional	Email address of the user.
`externalId`	string	Optional	External identifier.
`name`	object	Optional	Name object with givenName and familyName.
`emails`	object[]	Optional	Array of email objects.
`active`	boolean	Optional	Whether the user account is active.

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userName": "jane@example.com",
  "externalId": "ext-001",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "jane@example.com",
      "primary": true,
      "type": "work"
    }
  ],
  "active": true
}

Code Examples

curl -X POST "https://api.sutraid.com/scim/v2/my-org/Users" \
  -H "Authorization: Bearer <scim_token>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@example.com",
    "externalId": "ext-001",
    "name": { "givenName": "Jane", "familyName": "Doe" },
    "emails": [{ "value": "jane@example.com", "primary": true, "type": "work" }],
    "active": true
  }'

PATCH/scim/v2/:orgRef/Users/:userIdPatch SCIM userSCIM Token▾

Partially updates a SCIM user resource using RFC 7644 PATCH operations. Supports add, replace, and remove operations on userName, name, externalId, active, and enterprise extension attributes.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`
`userId`	string (UUID)	Required	SutraID user identifier.e.g. `a1b2c3d4-e5f6-7890-abcd-ef1234567890`

Request Body

Name	Type	Required	Description
`schemas`	string[]	Required	Must include urn:ietf:params:scim:api:messages:2.0:PatchOp.e.g. `["urn:ietf:params:scim:api:messages:2.0:PatchOp"]`
`Operations`	object[]	Required	Array of SCIM PATCH operations. Each operation has op (add/replace/remove), optional path, and optional value.e.g. `[{ "op": "replace", "path": "active", "value": false }]`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM User schema URN.
`id`	string	Optional	SutraID user identifier.
`userName`	string	Optional	Email address of the user.
`externalId`	string	Optional	External identifier.
`name`	object	Optional	Name object with givenName and familyName.
`emails`	object[]	Optional	Array of email objects.
`active`	boolean	Optional	Whether the user account is active.

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userName": "jane@example.com",
  "externalId": "ext-001",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "jane@example.com",
      "primary": true,
      "type": "work"
    }
  ],
  "active": false
}

Code Examples

curl -X PATCH "https://api.sutraid.com/scim/v2/my-org/Users/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <scim_token>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      { "op": "replace", "path": "active", "value": false }
    ]
  }'

DELETE/scim/v2/:orgRef/Users/:userIdDelete SCIM userSCIM Token▾

De-provisions a user via SCIM 2.0. The user is soft-deleted by setting their status to SUSPENDED in both the user record and their organization membership. Returns 204 No Content on success.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`
`userId`	string (UUID)	Required	SutraID user identifier.e.g. `a1b2c3d4-e5f6-7890-abcd-ef1234567890`

Response Example

{}

Code Examples

curl -X DELETE "https://api.sutraid.com/scim/v2/my-org/Users/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <scim_token>"

GET/scim/v2/:orgRef/GroupsList SCIM groupsSCIM Token▾

Returns a paginated SCIM 2.0 ListResponse of group resources for the organization. Supports filtering by displayName, externalId, or id.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`
`filter`	string	Optional	SCIM filter expression. Supports displayName eq, externalId eq, and id eq.e.g. `displayName eq "Engineering"`
`startIndex`	number	Optional	1-based index of the first result. Defaults to 1.e.g. `1`
`count`	number	Optional	Maximum number of results per page. Defaults to 100, maximum 200.e.g. `100`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM ListResponse schema URN.
`totalResults`	number	Optional	Total number of group resources matching the query.
`startIndex`	number	Optional	The 1-based index of the first result in the current set.
`itemsPerPage`	number	Optional	Number of resources returned in this response.
`Resources`	Group[]	Optional	Array of SCIM Group resources.
`Resources[].schemas`	string[]	Optional	SCIM Group schema URN.
`Resources[].id`	string	Optional	SutraID group identifier.
`Resources[].displayName`	string	Optional	Name of the group.
`Resources[].externalId`	string	Optional	External identifier from the identity provider.
`Resources[].members`	object[]	Optional	Array of member references with value (userId) and display (email).

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "g1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "displayName": "Engineering",
      "externalId": "grp-eng-001",
      "members": [
        {
          "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "display": "jane@example.com"
        }
      ]
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/scim/v2/my-org/Groups?startIndex=1&count=100" \
  -H "Authorization: Bearer <scim_token>"

GET/scim/v2/:orgRef/Groups/:groupIdGet SCIM group by IDSCIM Token▾

Returns a single SCIM 2.0 Group resource by its SutraID group identifier, including the full member list.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`
`groupId`	string (UUID)	Required	SutraID group identifier.e.g. `g1a2b3c4-d5e6-7890-abcd-ef1234567890`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM Group schema URN.
`id`	string	Optional	SutraID group identifier.
`displayName`	string	Optional	Name of the group.
`externalId`	string	Optional	External identifier from the identity provider.
`members`	object[]	Optional	Array of member references with value (userId) and display (email).

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "g1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "displayName": "Engineering",
  "externalId": "grp-eng-001",
  "members": [
    {
      "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "display": "jane@example.com"
    },
    {
      "value": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "display": "john@example.com"
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/scim/v2/my-org/Groups/g1a2b3c4-d5e6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <scim_token>"

POST/scim/v2/:orgRef/GroupsCreate SCIM groupSCIM Token▾

Provisions a new group via SCIM 2.0. Optionally includes initial members by user ID. Returns 201 on success.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`

Request Body

Name	Type	Required	Description
`displayName`	string	Required	Display name for the group.e.g. `Engineering`
`externalId`	string	Optional	External identifier from the upstream identity provider.e.g. `grp-eng-001`
`members`	object[]	Optional	Array of member objects. Each must have a value field containing the SutraID user ID.e.g. `[{ "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }]`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM Group schema URN.
`id`	string	Optional	SutraID group identifier.
`displayName`	string	Optional	Name of the group.
`externalId`	string	Optional	External identifier.
`members`	object[]	Optional	Array of member references with value (userId) and display (email).

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "g1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "displayName": "Engineering",
  "externalId": "grp-eng-001",
  "members": [
    {
      "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "display": "jane@example.com"
    }
  ]
}

Code Examples

curl -X POST "https://api.sutraid.com/scim/v2/my-org/Groups" \
  -H "Authorization: Bearer <scim_token>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "Engineering",
    "externalId": "grp-eng-001",
    "members": [
      { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
    ]
  }'

PATCH/scim/v2/:orgRef/Groups/:groupIdPatch SCIM groupSCIM Token▾

Partially updates a SCIM group resource using RFC 7644 PATCH operations. Supports add, replace, and remove operations on displayName and members.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`
`groupId`	string (UUID)	Required	SutraID group identifier.e.g. `g1a2b3c4-d5e6-7890-abcd-ef1234567890`

Request Body

Name	Type	Required	Description
`schemas`	string[]	Required	Must include urn:ietf:params:scim:api:messages:2.0:PatchOp.e.g. `["urn:ietf:params:scim:api:messages:2.0:PatchOp"]`
`Operations`	object[]	Required	Array of SCIM PATCH operations. Supports add/replace/remove on displayName and members. Use members[value eq "..."] path to remove specific members.e.g. `[{ "op": "add", "path": "members", "value": [{ "value": "user-uuid" }] }]`

Response Fields

Name	Type	Required	Description
`schemas`	string[]	Optional	SCIM Group schema URN.
`id`	string	Optional	SutraID group identifier.
`displayName`	string	Optional	Name of the group.
`externalId`	string	Optional	External identifier.
`members`	object[]	Optional	Updated array of member references.

Response Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "g1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "displayName": "Engineering",
  "externalId": "grp-eng-001",
  "members": [
    {
      "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "display": "jane@example.com"
    },
    {
      "value": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "display": "john@example.com"
    }
  ]
}

Code Examples

curl -X PATCH "https://api.sutraid.com/scim/v2/my-org/Groups/g1a2b3c4-d5e6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <scim_token>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [{ "value": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }]
      }
    ]
  }'

DELETE/scim/v2/:orgRef/Groups/:groupIdDelete SCIM groupSCIM Token▾

Permanently deletes a group and removes all group memberships. Returns 204 No Content on success.

Parameters

Name	Type	Required	Description
`orgRef`	string	Required	Organization identifier -- a UUID, slug, or legacy org_ prefixed reference.e.g. `my-org`
`groupId`	string (UUID)	Required	SutraID group identifier.e.g. `g1a2b3c4-d5e6-7890-abcd-ef1234567890`

Response Example

{}

Code Examples

curl -X DELETE "https://api.sutraid.com/scim/v2/my-org/Groups/g1a2b3c4-d5e6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <scim_token>"