Skip to main content
API docs by Redocly

Beyond Identity Secure Workforce Admin API (2.4.1)

Download OpenAPI specification:Download

E-mail: [email protected]

Introduction

The Beyond Identity Secure Workforce Admin API defines methods for administrative duties for your Beyond Identity tenant.

This API is currently in the early-access stage with limited endpoints implemented. We encourage feedback and suggestions through [email protected].

Authentication

All Beyond Identity API endpoints require authentication using an access token. The access token is generated through OAuth 2.0, using the client credentials flow. Follow these steps:

  1. Navigate to the Beyond Identity Secure Workforce Admin Console.
  2. Under the Settings tab in the side panel, select the API Access tab and create a set of client credentials.
  3. Use the client ID and client secret to exchange the client credentials for an access token. You can use the following cURL call below:
curl https://api.byndid.com/v2/oauth2/token \
  -X POST \
  -u "$CLIENT_ID:$CLIENT_SECRET" --basic \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

Alternatively, an access token may also be generated via the Admin Console.

  1. Navigate to the Beyond Identity Secure Workforce Admin Console.
  2. Under the Settings tab in the side panel, select the API Access tab and create a set of client credentials.
  3. Next, select the created client credentials, navigate to the Tokens tab, and click Create token.

Once you've obtained the access token, you must provide it in the Authorization header of any API request.

curl https://api.byndid.com/v2/... \
  -X $HTTP_METHOD -H "Authorization: Bearer $TOKEN"

Rate Limiting

The Beyond Identity public API is subject to rate limiting to ensure a consistent quality of service for our customers. Rate limits are enforced per tenant, if you are experiencing issues with the default rate limits provided, please refer to our support page.

When a request exceeds a rate limit, our application server returns an HTTP 429 status code and RateLimit-* headers, as described in RateLimit Header Fields for HTTP. Example response:

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 30
RateLimit-Remaining: 0
RateLimit-Reset: 7

Authorization

Each method will have associated scopes. See the Authorizations portion within each method to see the scopes.

The access token used must contain all scopes for the method to be able to access the endpoint.

Requests and Responses

When interacting with the Beyond Identity Secure Workforce Admin API, all requests must be made over HTTPS.

The Beyond Identity API is structured as a resource-oriented API. Resources are represented as JSON objects and are used as both inputs to and outputs from API methods.

Resource fields can be read-only and immutable. For example, system-generated IDs are both read-only and immutable.

  • A read-only field is provided only in the response.
  • An immutable field is assigned only once and cannot be changed.

Create a new resource

Create requests use the POST method and include the necessary attributes to create a new resource. Create operations return the created resource in the response.

Retrieve resources

Retrieve requests use the GET method. You can retrieve a single resource or a collection of resources. When retrieving a collection of resources, the response includes an array of JSON objects keyed on the plural name of the requested resource.

Update resources

Update requests use the PATCH method. Update operations support partial updating, so you can specify only the attributes you want to update. Update operations return the updated resource in the response.

Delete resources

Delete requests use the DELETE method, which returns an empty response instead of returning the resource in the response.

Example response for a user

{
  "id": "b60a8085-2508-46d8-8ef6-aba593afaac2",
  "tenant_id": "acme-corp",
  "username": "alice.acmecorp"
  "display_name": "Alice Acmecorp",
  "create_time": "2022-06-22T21:46:08.930278Z",
  "update_time": "2022-06-22T21:46:08.930278Z",
  ...
}

Example response for a collection of users

{
  "users": [
    {
      "id": "b60a8085-2508-46d8-8ef6-aba593afaac2",
      "tenant_id": "acme-corp",
      "username": "alice.acmecorp"
      "display_name": "Alice Acmecorp",
      "create_time": "2022-06-22T21:46:08.930278Z",
      "update_time": "2022-06-22T21:46:08.930278Z",
      ...
    }
  ],
  "total_size": 1
}

HTTP statuses

The API returns standard HTTP statuses and error codes.

Code range Description
200 The request was fulfilled successfully with no errors.
400 There was an issue with the request that the client may address. For example, client errors may indicate that the request was missing proper authorization or was malformed.
500 The server encountered an internal issue and could not fulfill the request.

All error responses include a JSON object with a code field and a message field.

  • code has a human-readable name for the HTTP status code, and
  • message has a high-level description of the error.

The error can also have additional details that the client can use to determine the exact cause of the error. Refer to each API method's examples to determine the specific error detail types supported for that method.

Invalid access token example

If the provided access token is invalid, you will receive a 401 error. This error indicates that the token is not recognized or was not generated by Beyond Identity.

HTTP/1.1 401 Unauthorized
{
  "code": "unauthorized",
  "message": "unauthorized"
}

Permission denied example

If the provided access token does not have access to the requested resource, you will receive a 403 error. Access tokens are scoped at a minimum to your tenant. Any request for resources outside of your tenant will result in this error.

HTTP/1.1 403 Forbidden
{
  "code": "forbidden",
  "message": "forbidden"
}

Missing resource example

If the requested resource does not exist, you'll receive a 404 error. The specific API method may return additional details about the missing resource.

HTTP/1.1 404 Not Found
{
  "code": "not_found",
  "message": "user not found"
  "details": [
    {
      "type": "ResourceInfo",
      "resource_type": "User",
      "id": "348afd29-f265-4eee-9451-1fcf71832e77",
      "description": "user not found"
    }
  ],
}

Invalid parameters example

If the request body contains invalid parameters, you'll receive a 400 error. The specific API method may return additional details about the invalid parameter.

HTTP/1.1 400 Bad Request
{
  "code": "bad_request",
  "message": "invalid parameters"
  "details": [
    {
      "type": "FieldViolations"
      "field_violations": [
        {
          "description": "missing",
          "field": "user.display_name"
        }
      ],
    }
  ],
}

Too many requests example

If the caller has exceeded their rate limit they may receive a 429 error. When receiving a 429 response, clients should use the rate limit headers to determine when to retry their request. The response includes the following headers:

  • RateLimit-Limit: The maximum number of requests allowed in the current time window
  • RateLimit-Remaining: The number of requests remaining in the current window
  • RateLimit-Reset: The number of seconds until the rate limit window resets
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 1
RateLimit-Remaining: 0
RateLimit-Reset: 30

Clients should wait until the rate limit window resets (indicated by RateLimit-Reset) before retrying their request. The rate limit headers follow the IETF draft specification

SCIM vs. Native APIs

Beyond Identity provides two sets of APIs for managing users and groups: SCIM APIs and native Directory APIs. Understanding when to use each API set is important for successful integration:

SCIM APIs (/scim/v2/*)

  • Use SCIM APIs primarily for synchronizing users and groups from your identity provider (IdP) into Beyond Identity's directory
  • Important: Objects must be created through SCIM to be manageable via SCIM APIs
  • Best suited for automated user provisioning and deprovisioning workflows
  • Follows the SCIM 2.0 specification (RFC7643 and RFC7644) for standardized identity management

Native Directory APIs (/v2/*)

  • Use these APIs for audit, observability, and administrative operations
  • Provides more detailed control and visibility into Beyond Identity-specific features
  • Best suited for building custom integrations and automation workflows
  • Recommended for retrieving user and group information for reporting or monitoring purposes

Choose SCIM APIs when integrating with identity providers and automated provisioning systems. Use native Directory APIs when building custom applications or requiring detailed audit and administrative capabilities.

Users

A user is a member of an organization using Beyond Identity.

Create a new user

To create a user, send a POST request to /v2/users. Values in the request body for read-only fields get ignored. If the request conflicts with an existing resource, you'll receive a 409 error. When the user gets created, they'll receive a Beyond Identity enrollment email sent to the email address in the request.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object (User)

A user is a member of an organization that uses Beyond Identity.

external_id
string

A required unique identifier for the user within the tenant.

email_address
string

A required email address serving as primary contact for user.

username
string

A required username for the user.

display_name
string

A required human-readable name for the user that is used for display purposes.

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "id": "f7277b07-4a9e-4f84-9839-cd3082a6b8c3",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "last_auth_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "external_id": "0001f1f460b1ace6",
  • "email_address": "[email protected]",
  • "username": "alice.acmecorp",
  • "display_name": "Alice Acmecorp",
  • "state": "ACTIVE",
  • "source": "scim",
  • "has_active_passkey": true
}

List all users for a tenant

To list all users for a tenant, send a GET request to /v2/users.

The response will have up to 1000 items. The response will be empty if the page size is not specified (i.e., the default). By default, the list is in ascending order by create_time. The maximum and default page sizes are subject to change.

When paginating, use the skip parameter as the offset.

When filtering, the response will only show users that satisfy this filter. The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

The supported fields and their supported operations are:

  • id (eq, ne, co, sw, ew)
  • email_address (eq, ne, co, sw, ew)
  • external_id (eq, ne, co, sw, ew)
  • username (eq, ne, co, sw, ew)
  • display_name (eq, ne, co, sw, ew)
  • state (eq, ne, co, sw, ew)
  • source (eq, ne, co, sw, ew)
  • last_auth_time (pr, eq, ne, gt, lt, ge, le)
  • has_active_passkey (eq, ne)

When sorting, use the order_by parameter. It's a comma-delimited list of attributes. Currently, the following fields are supported:

  • display_name
  • username
  • email_address
  • status
  • source
  • last_auth_time

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Authorizations:
BearerAuth
query Parameters
page_size
integer <uint32> >= 0

The number of items returned per page. The response may include this exact number or fewer. If omitting this value, the response returns the default number of results the method allows.

skip
integer <uint32> >= 0
Default: 0

Number of items to skip. This is the zero-based index of the first result.

filter
string

Filter query for responses.

The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

See individual methods for the supported attributes and operations.

Ex. name co "alice"

order_by
string

A comma-delimited list of attributes to sort results.

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Ex. name desc

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "total_size": 1
}

Retrieve an existing user

To retrieve an existing user for a tenant, send a GET request to /v2/users/$USER_ID.

Authorizations:
BearerAuth
path Parameters
user_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a user.

Responses

Response samples

Content type
application/json
{
  • "id": "f7277b07-4a9e-4f84-9839-cd3082a6b8c3",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "last_auth_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "external_id": "0001f1f460b1ace6",
  • "email_address": "[email protected]",
  • "username": "alice.acmecorp",
  • "display_name": "Alice Acmecorp",
  • "state": "ACTIVE",
  • "source": "scim",
  • "has_active_passkey": true
}

Update a user

To update only specific attributes of an existing user, send a PATCH request to /v2/users/$USER_ID. Values in the request body for immutable or read-only fields get ignored. Fields omitted from the request body will be left unchanged. If the request conflicts with an existing resource, you'll receive a 409 error.

Authorizations:
BearerAuth
path Parameters
user_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a user.

Responses

Response samples

Content type
application/json
{
  • "id": "f7277b07-4a9e-4f84-9839-cd3082a6b8c3",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "last_auth_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "external_id": "0001f1f460b1ace6",
  • "email_address": "[email protected]",
  • "username": "alice.acmecorp",
  • "display_name": "Alice Acmecorp",
  • "state": "ACTIVE",
  • "source": "scim",
  • "has_active_passkey": true
}

Delete a user

To delete a user for a tenant, send a DELETE request to /v2/users/$USER_ID. A successful request will receive a 200 status code with nothing in the response's body. This indicates that the request was processed successfully.

Authorizations:
BearerAuth
path Parameters
user_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a user.

Responses

Response samples

Content type
application/json
{
  • "code": "unauthorized",
  • "message": "unauthorized"
}

Groups

Create a new group

To create a group, send a POST request to /v2/groups. Values in the request body for read-only attributes get ignored.

If the requested group name is already in use, you'll receive a 409 error.

Note that this endpoint does not support creating permission groups. If the request attempts to create a group with the name of a permission group, you will receive a 403 error.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object (Group)

A group is a collection of members within an organization that uses Beyond Identity.

name
string

A required unique name for the group within the tenant.

description
string

A required description for the group within the tenant.

Responses

Request samples

Content type
application/json
{
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "name": "Acme Group",
  • "description": "Members of the Acme Group",
  • "source": "scim"
}

List all groups for a tenant

To list all groups for a tenant, send a GET request to /v2/groups. Note that this endpoint excludes permission groups.

The response will have up to 1000 items. The response will be empty if the page size is not specified (i.e., the default). By default, the list is in ascending order by create_time. The maximum and default page sizes are subject to change.

When paginating, use the skip parameter as the offset.

When filtering, the response will only show users that satisfy this filter. The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)

The supported fields and their supported operations are:

  • id (eq, ne, co, sw, ew)
  • name (eq, ne, co, sw, ew)
  • description (eq, ne, co, sw, ew)
  • source (eq, ne, co, sw, ew)

When sorting, use the order_by parameter. It's a comma-delimited list of attributes. Currently, the following fields are supported:

  • name
  • source

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Authorizations:
BearerAuth
query Parameters
page_size
integer <uint32> >= 0

The number of items returned per page. The response may include this exact number or fewer. If omitting this value, the response returns the default number of results the method allows.

skip
integer <uint32> >= 0
Default: 0

Number of items to skip. This is the zero-based index of the first result.

filter
string

Filter query for responses.

The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

See individual methods for the supported attributes and operations.

Ex. name co "alice"

order_by
string

A comma-delimited list of attributes to sort results.

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Ex. name desc

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "total_size": 1
}

Retrieve an existing group

To retrieve an existing group, send a GET request to /v2/groups/$GROUP_ID.

Note that this endpoint does not support access to permission groups. If the request attempts to access a permission group, you'll receive a 403 error.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

Responses

Response samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "name": "Acme Group",
  • "description": "Members of the Acme Group",
  • "source": "scim"
}

Patch a group

To update only specific attributes of an existing group, send a PATCH request to /v2/groups/$GROUP_ID. Values in the request body for read-only attributes get ignored. Fields omitted from the request body will be left unchanged.

If the updated name of the group is already in use, you'll receive a 409 error.

Note that this endpoint does not support updates to permission groups. If the request attempts to use the name of a permission group or attempts to update a permission group, you'll receive a 403 error.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

Request Body schema: application/json
required
object (Group)

A group is a collection of members within an organization that uses Beyond Identity.

name
string

A required unique name for the group within the tenant.

description
string

A required description for the group within the tenant.

Responses

Request samples

Content type
application/json
{
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "name": "Acme Group",
  • "description": "Members of the Acme Group",
  • "source": "scim"
}

Delete a group

To delete a group, send a DELETE request to /v2/groups/$GROUP_ID.

A successful request will receive a 200 status code with nothing in the response's body. This indicates that the request was processed successfully.

Note that this endpoint does not support deleting permission groups. If the request attempts to delete a permission group, you'll receive a 403 error.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

Responses

Response samples

Content type
application/json
{
  • "code": "unauthorized",
  • "message": "unauthorized"
}

List all users for a group

To list all users belonging to a group, send a GET request to /v2/groups/$GROUP_ID:listUsers.

The response will have up to 1000 items. The response will be empty if the page size is not specified (i.e., the default). By default, the list is in ascending order by create_time. The maximum and default page sizes are subject to change.

When paginating, use the skip parameter as the offset.

When filtering, the response will only show users that satisfy this filter. The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

The supported fields and their supported operations are:

  • id (eq, ne, co, sw, ew)
  • email_address (eq, ne, co, sw, ew)
  • external_id (eq, ne, co, sw, ew)
  • username (eq, ne, co, sw, ew)
  • display_name (eq, ne, co, sw, ew)
  • state (eq, ne, co, sw, ew)
  • source (eq, ne, co, sw, ew)
  • last_auth_time (pr, eq, ne, gt, lt, ge, le)
  • has_active_passkey (eq, ne)

When sorting, use the order_by parameter. It's a comma-delimited list of attributes. Currently, the following fields are supported:

  • display_name
  • username
  • email_address
  • status
  • source
  • last_auth_time

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

query Parameters
page_size
integer <uint32> >= 0

The number of items returned per page. The response may include this exact number or fewer. If omitting this value, the response returns the default number of results the method allows.

skip
integer <uint32> >= 0
Default: 0

Number of items to skip. This is the zero-based index of the first result.

filter
string

Filter query for responses.

The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

See individual methods for the supported attributes and operations.

Ex. name co "alice"

order_by
string

A comma-delimited list of attributes to sort results.

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Ex. name desc

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "total_size": 1
}

Add users to a group

To add users to a group, send a POST request to /v2/groups/$GROUP_ID:addUsers. The request may include up to 1000 users to add. Users which already belong to the group will be ignored.

Note that this endpoint does not support adding users to permission groups. If the request attempts to add users to a permission group, you'll receive a 403 error.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

Request Body schema: application/json
id
string

ID of the group.

user_ids
Array of strings [ 1 .. 1000 ] items

IDs of the users to be added to the group.

Responses

Request samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "user_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "name": "Acme Group",
  • "description": "Members of the Acme Group",
  • "source": "scim"
}

Delete users from a group

To delete users from a group, send a POST request to /v2/groups/$GROUP_ID:deleteUsers. The request may contain up to 1000 users to delete. Users which already do not belong to the group will be ignored.

Note that this endpoint does not support deleting users from permission groups. If the request attempts to delete users from a permission group, you'll receive a 403 error.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

Request Body schema: application/json
id
string

ID of the group.

user_ids
Array of strings [ 1 .. 1000 ] items

IDs of the users to be deleted from the group.

Responses

Request samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "user_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "name": "Acme Group",
  • "description": "Members of the Acme Group",
  • "source": "scim"
}

BindingJobs

Create a new credential binding job

To create a binding job, send a POST request to /v2/binding-jobs. Values in the request body for read-only attributes get ignored.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object (BindingJob)

A binding job tracks the process of binding a new credential for a user.

ttl_seconds
integer <uint32> [ 60 .. 900 ]
Default: 60

Number of seconds until the binding job expires. This must be between 1 minute (60 seconds) and 15 minutes (900 seconds). This field is used only if the expire_time on the requested binding job is unspecified. This field defaults to 1 minute (60 seconds).

Responses

Request samples

Content type
application/json
Example
{
  • "binding_job": {
    }
}

Response samples

Content type
application/json
{
  • "id": "66d36cf5-96df-4fa3-a5d0-36d0aa8487c3",
  • "tenant_id": "acme-corp",
  • "user_id": "11819414-9000-4700-af07-2743c02d68ca",
  • "issuer_user_id": "4dfb7751-46a9-4bd6-a591-a5941cb24eba",
  • "delivery_method": "SHORT_CODE",
  • "short_code_delivery_details": {
    }
}

SCIM

Create a New User

To create a user, send a POST request to /Users. Values in the request body for read-only fields will be ignored.

Important notes about email handling:

  • Only one email address is supported per user
  • The email must be marked as primary (primary: true)
  • If multiple email addresses are provided, only the primary email will be used and all others will be ignored
Authorizations:
BearerAuth
Request Body schema: application/json
schemas
required
Array of strings

The list of schemas used to define the user. This must contain only the core User schema ("urn:ietf:params:scim:schemas:core:2.0:User").

externalId
required
string

The provisioning client's unique identifier for the resource. This value must be unique across all users.

userName
required
string non-empty

The unique username of the user. The value of this field will be returned as the subject of an OIDC ID Token.

displayName
required
string non-empty

Display name of the User. This name is used for display purposes.

active
required
boolean

Indicator for the user's administrative status. If true, the user has administrative capabilities.

required
Array of objects

The list containing the user's emails. Important notes about email handling: - Only one email address is supported per user - The email must be marked as primary (primary: true) - If multiple email addresses are provided, only the primary email will be used and all others will be ignored

object

Definition of the user's name.

Responses

Request samples

Content type
application/json
{
  • "schemas": [
    ],
  • "userName": "bjensen",
  • "externalId": "bjensen",
  • "active": true,
  • "displayName": "Barbara Jensen",
  • "name": {
    },
  • "emails": []
}

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "2819c223-7f76-453a-919d-413861904646",
  • "externalId": "bjensen",
  • "userName": "bjensen",
  • "name": {
    },
  • "displayName": "Ms. Barbara J Jensen III",
  • "active": true,
  • "emails": [],
  • "groups": [
    ],
  • "meta": {
    }
}

List All Users

To list all users, send a GET request to /Users.

Currently, filtering on users only supports the eq and ne operators and the userName and externalId attributes.

The response will contain at most 1000 items. If count is not specified or is zero, the response will not contain any resources. There is no defined ordering of the list of users in the response. Note that the maximum page size is subject to change.

Authorizations:
BearerAuth
query Parameters
filter
string
Example: filter=displayName eq "John Doe"

Filter for list methods.

Filters follow the SCIM grammar from RFC 7644 Section 3.4.2.2.

count
integer <uint32> >= 0
Default: 0

Specifies the desired maximum number of query results per page. A negative value is treated as 0, which indicates that the response should not contain any resources. Note that the response may include fewer results than the requested count.

startIndex
integer <uint32> >= 0
Default: 0

The 1-based index of the first query result.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "Resources": [
    ],
  • "itemsPerPage": 1000,
  • "startIndex": 1,
  • "totalResults": 1
}

Retrieve an Existing User

To retrieve an existing user, send a GET request to /Users/$USER_ID. The response will contain a full representation of the User resource matching the specified identifier. Per RFC-7644 §3.4.1, the server will respond with HTTP status 200 and the resource if found, or 404 if not found.

Authorizations:
BearerAuth
path Parameters
user_id
required
string non-empty

ID of the user.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "ed9fcce6-ec82-458e-ae58-e2d975cfc32d",
  • "externalId": "external-id-abcdef",
  • "userName": "test_user",
  • "displayName": "Test User",
  • "active": true,
  • "emails": [],
  • "name": {
    },
  • "groups": [
    ],
  • "meta": {
    }
}

Patch a User

To update only specific attributes of an existing user, send a PATCH request to /Users/$USER_ID. The PATCH operation is defined by RFC-7644 §3.5.2.

The request body MUST contain a valid SCIM PATCH request with a "schemas" value of "urn:ietf:params:scim:api:messages:2.0:PatchOp" and an "Operations" array with one or more PATCH operations.

Values in the request body for immutable or read-only fields (as defined in RFC-7643 §4.1) will be ignored. Fields that are omitted from the request body will be left unchanged.

Important implementation notes:

  • The Beyond Identity SCIM server currently does not support atomic PATCH operations
  • The server supports two types of PATCH operations:
    1. Email Update: Must use "add" operation with path "emails" and value containing the email object (see "Update Email" example)
    2. Generic Update: A path which isn't equal to "emails" is ignored and the value must be a JSON object representing the user resource
  • If a request contains multiple operations, the request may be partially applied:
    1. The server first validates the overall request schema and attribute types
    2. Operations are then applied sequentially in the order provided
    3. If any operation fails, processing stops immediately
    4. Previously successful operations remain applied
    5. The error response does not indicate which operation failed or which operations were applied
    6. To determine the current state, clients should issue a GET request after receiving an error

Important notes about email handling:

  • Only one email address is supported per user
  • The email must be marked as primary (primary: true)
  • If multiple email addresses are provided, only the primary email will be used and all others will be ignored
Authorizations:
BearerAuth
path Parameters
user_id
required
string non-empty

ID of the user.

Request Body schema: application/json
schemas
required
Array of strings
required
Array of objects

Responses

Request samples

Content type
application/json
Example
{
  • "schemas": [
    ],
  • "Operations": [
    ]
}

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "2819c223-7f76-453a-919d-413861904646",
  • "externalId": "bjensen",
  • "userName": "bjensen",
  • "name": {
    },
  • "displayName": "Ms. Barbara J Jensen III",
  • "active": true,
  • "emails": [],
  • "groups": [
    ],
  • "meta": {
    }
}

Replace a User

To replace all attributes of an existing user, send a PUT request to /Users/$USER_ID. As specified in RFC-7644 §3.5.1, this operation performs a complete replacement of all attributes except server-managed attributes. Values in the request body for immutable or read-only fields will be ignored. If an attribute is not specified in the request, it will be removed or reset to its default value. Important notes about email handling: - Only one email address is supported per user - The email must be marked as primary (primary: true) - If multiple email addresses are provided, only the primary email will be used and all others will be ignored

Authorizations:
BearerAuth
path Parameters
user_id
required
string non-empty

ID of the user.

Request Body schema: application/json
required
object (User)

A user represents a human entity as defined by RFC 7643 Section 4.1.

The externalId attribute must be unique across all users in the system.

schemas
required
Array of strings

The list of schemas used to define the user. This must contain only the core User schema ("urn:ietf:params:scim:schemas:core:2.0:User").

externalId
string

The provisioning client's unique identifier for the resource. This value must be unique across all users.

userName
string non-empty

The unique username of the user. The value of this field will be returned as the subject of an OIDC ID Token.

displayName
string non-empty

Display name of the User. This name is used for display purposes.

active
boolean

Indicator for the user's administrative status. If true, the user has administrative capabilities.

Array of objects

The list containing the user's emails. Important notes about email handling: - Only one email address is supported per user - The email must be marked as primary (primary: true) - If multiple email addresses are provided, only the primary email will be used and all others will be ignored

object

Definition of the user's name.

object (Meta)

Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Content type
application/json
{
  • "schemas": [
    ],
  • "active": true,
  • "userName": "bjensen",
  • "externalId": "bjensen",
  • "displayName": "Ms. Barbara J Jensen III",
  • "name": {
    },
  • "emails": []
}

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "2819c223-7f76-453a-919d-413861904646",
  • "externalId": "bjensen",
  • "userName": "bjensen",
  • "name": {
    },
  • "displayName": "Ms. Barbara J Jensen III",
  • "active": true,
  • "emails": [],
  • "groups": [
    ],
  • "meta": {
    }
}

Delete a User

To delete a user, send a DELETE request to /Users/$USER_ID. As specified in RFC-7644 §3.6, a successful delete operation returns HTTP status 204 (No Content). If the resource does not exist, HTTP status 404 is returned.

Note that deleting a user:

  • Is permanent and cannot be undone
  • Will remove all associated authentication data
  • Will remove the user from all groups
Authorizations:
BearerAuth
path Parameters
user_id
required
string non-empty

ID of the user.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "status": "400",
  • "scimType": "invalidValue",
  • "detail": "A required value was missing, or the value specified was not compatible with the operation or attribute type, or resource schema."
}

Create a New Group

Creates a new SCIM Group resource. Send a POST request to /Groups with a JSON body containing the group attributes. The server will generate any required unique identifiers for the new Group. As per RFC-7644 §3.3, the response includes a Location header pointing to the newly created resource. Read-only attributes (e.g., 'id', 'meta') specified in the request body will be ignored. The service provider will evaluate the request body against the Group schema defined in RFC-7643 §4.2 to ensure validity. If the request body fails validation, a 400 error will be returned with details about the validation failure.

Authorizations:
BearerAuth
Request Body schema: application/json
schemas
required
Array of strings

The list of schemas used to define the group. This must contain the core Group schema ("urn:ietf:params:scim:schemas:core:2.0:Group") and may include the custom Beyond Identity Group schema extension ("urn:scim:schemas:extension:byndid:1.0:Group").

displayName
required
string non-empty

The unique display name of the group. This name is used for display purposes.

Array of objects

The list of the group's members. Please note that only users can be added as members. If a non-existing user is specified, the endpoint will return a 404 error.

object

The Beyond Identity Group schema extension.

Responses

Request samples

Content type
application/json
Example
{
  • "schemas": [
    ],
  • "displayName": "Test Group"
}

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "22e7c78c-39ff-4501-8ed4-32d0479e54c1",
  • "displayName": "Test Group",
  • "members": [
    ],
  • "urn:scim:schemas:extension:byndid:1.0:Group": {
    },
  • "meta": {
    }
}

List All Groups

Retrieves a list of SCIM Group resources that match the specified filter criteria. Send a GET request to /Groups.

Note that this method excludes the RBAC access groups as well as groups created through the Admin Console.

Filtering (RFC-7644 §3.4.2.2):

  • Supports 'eq' (equals) and 'ne' (not equals) operators
  • Filterable attributes: displayName
  • Example: filter=displayName eq "Engineering"

Pagination (RFC-7644 §3.4.2.4):

  • Use startIndex (1-based) and count parameters
  • Maximum page size: 1000 items
  • If count is not specified or is zero, no resources will be returned
  • Response includes totalResults for determining additional pages

Sorting:

  • No sorting parameters are supported; response order is undefined
Authorizations:
BearerAuth
query Parameters
filter
string
Example: filter=displayName eq "John Doe"

Filter for list methods.

Filters follow the SCIM grammar from RFC 7644 Section 3.4.2.2.

count
integer <uint32> >= 0
Default: 0

Specifies the desired maximum number of query results per page. A negative value is treated as 0, which indicates that the response should not contain any resources. Note that the response may include fewer results than the requested count.

startIndex
integer <uint32> >= 0
Default: 0

The 1-based index of the first query result.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "Resources": [
    ],
  • "itemsPerPage": 1000,
  • "startIndex": 1,
  • "totalResults": 1
}

Retrieve an existing group

To retrieve an existing group, send a GET request to /Groups/$GROUP_ID. The response will contain a full representation of the Group resource matching the specified identifier. Per RFC-7644 §3.4.1, the server will respond with HTTP status 200 and the resource if found, or 404 if not found.

Note that this method can be used to retrieve RBAC permission groups as well as other groups created through the Admin Console.

Authorizations:
BearerAuth
path Parameters
group_id
required
string non-empty

ID of the group.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "ed9fcce6-ec82-458e-ae58-e2d975cfc32d",
  • "displayName": "Help Desk",
  • "members": [],
  • "urn:scim:schemas:extension:byndid:1.0:Group": {
    },
  • "meta": {
    }
}

Patch a Group

To update specific attributes of an existing group, send a PATCH request to /Groups/$GROUP_ID. The PATCH operation is defined by RFC-7644 §3.5.2.

The request body MUST contain a valid SCIM PATCH request with a "schemas" value of "urn:ietf:params:scim:api:messages:2.0:PatchOp" and an "Operations" array with one or more PATCH operations (add, remove, or replace).

Values in the request body for immutable or read-only fields (as defined in RFC-7643 §4.2) will be ignored. Fields that are omitted from the request body will be left unchanged.

Note: The Beyond Identity SCIM server currently does not support atomic PATCH operations. If a request contains multiple operations, the request may be partially applied.

The Beyond Identity SCIM server also does not support modifying both a group's attributes and its membership in the same operation. For example, a PATCH request to update a group's display name and its membership should specify two separate operations, one to update the display name and the other to modify the membership.

If a request contains multiple operations, the request may be partially applied:

  1. The server first validates the overall request schema and attribute types
  2. Operations are then applied sequentially in the order provided
  3. If any operation fails, processing stops immediately
  4. Previously successful operations remain applied
  5. The error response does not indicate which operation failed or which operations were applied
  6. To determine the current state, clients should issue a GET request after receiving an error

Note that this method cannot be used to update any groups which were not created by SCIM, e.g. RBAC permission groups or other groups created through the Admin Console.

Authorizations:
BearerAuth
path Parameters
group_id
required
string non-empty

ID of the group.

Request Body schema: application/json
schemas
required
Array of strings
required
Array of objects

Responses

Request samples

Content type
application/json
Example
{
  • "schemas": [
    ],
  • "Operations": [
    ]
}

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "22e7c78c-39ff-4501-8ed4-32d0479e54c1",
  • "displayName": "Test Group",
  • "members": [
    ],
  • "urn:scim:schemas:extension:byndid:1.0:Group": {
    },
  • "meta": {
    }
}

Delete a Group

To delete a group, send a DELETE request to /Groups/$GROUP_ID. As specified in RFC-7644 §3.6, a successful delete operation returns HTTP status 204 (No Content). If the resource does not exist, HTTP status 404 is returned.

Note that this method cannot be used to delete any groups which were not created by SCIM, e.g. RBAC permission groups or other groups created through the Admin Console.

Authorizations:
BearerAuth
path Parameters
group_id
required
string non-empty

ID of the group.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "status": "400",
  • "scimType": "invalidValue",
  • "detail": "A required value was missing, or the value specified was not compatible with the operation or attribute type, or resource schema."
}

List All Resource Types

To list all supported resource types, send a GET request to /ResourceTypes.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "Resources": [
    ],
  • "itemsPerPage": 1000,
  • "startIndex": 1,
  • "totalResults": 2
}

List All Schemas

To list all supported resource schemas, send a GET request to /Schemas.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "Resources": [
    ],
  • "itemsPerPage": 1000,
  • "startIndex": 1,
  • "totalResults": 3
}

Retrieve the Service Provider Configuration

To retrieve the service provider configuration, send a GET request to /ServiceProviderConfig.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "authenticationSchemes": [
    ],
  • "bulk": {
    },
  • "changePassword": {
    },
  • "documentationUri": "",
  • "etag": {
    },
  • "filter": {
    },
  • "patch": {
    },
  • "sort": {
    }
}