Beyond Identity API (1.7.0)

Download OpenAPI specification:Download

Introduction

The Beyond Identity API defines methods for managing realms, directories, credentials, and applications.

All of the functionality available in the Beyond Identity Admin Console is also available through the API.

This API is currently in the early-access stage and is under active development. Feedback and suggestions are encouraged and should be directed to the Beyond Identity Developer Slack Channel.

Authentication

All Beyond Identity API endpoints require authentication using an access token. The access token is generated through OAuth 2.0 or OIDC, using the authorization code flow or the client credentials flow. The simplest way to acquire an access token is through the Beyond Identity Admin Console. Under the "Applications" tab, select the "Beyond Identity Management API" application, navigate to the "API Tokens" tab, and then click on "Create token".

Alternatively, an access token may also be generated directly via the API by requesting a token for the "Beyond Identity Management API" Application.

curl https://auth-us.beyondidentity.com/v1/tenants/$TENANT_ID/realms/$REALM_ID/applications/$APPLICATION_ID/token \
  -X POST \
  -u "$CLIENT_ID:$CLIENT_SECRET" --basic \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=$SCOPES"

This will work for any application that you have configured to provide access to the Beyond Identity Management API Resource Server. The "Beyond Identity Management API" application is provided by default as part of the tenant onboarding process.

The access token must be provided in the Authorization header of the API request.

curl https://api-us.beyondidentity.com/v1/... \
  -X $HTTP_METHOD -H "Authorization: Bearer $TOKEN"

Requests and Responses

To interact with the Beyond Identity API, all requests should be made over HTTPS.

The Beyond Identity API is generally 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 may be described as read-only and immutable. A read-only field is only provided on the response. An immutable field is only assigned once and may not be changed after. For example, system-generated IDs are described as both read-only and immutable.

To create a new resource, requests should use the POST method. Create requests include all of the necessary attributes to create a new resource. Create operations return the created resource in the response.

To retrieve a single resource or a collection of resources, requests should use the GET method. When retrieving a collection of resources, the response will include an array of JSON objects keyed on the plural name of the requested resource.

To update an resource, requests should use the PATCH method. Update operations support partial updating so requests may specify only the attributes which should be updated. Update operations return the updated resource in the response.

To delete a resource, requests should use the DELETE method. Note that delete operations return an empty response instead of returning the resource in the response.

Example Response for a Realm

{
  "id": "a448fe493e02fa9f",
  "tenant_id": "000168dc50bdce49",
  "display_name": "Test Realm",
  "create_time": "2022-06-22T21:46:08.930278Z",
  "update_time": "2022-06-22T21:46:08.930278Z"
}

Example Response for a Collection of Realms

{
  "realms": [
    {
      "id": "a448fe493e02fa9f",
      "tenant_id": "000168dc50bdce49",
      "display_name": "Test Realm",
      "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.

Statuses in the 200 range indicate that the request was successfully fulfilled and there were no errors.

Statuses in the 400 range indicate that there was an issue with the request that may be addressed by the client. For example, client errors may indicate that the request was missing proper authorization or that the request was malformed.

Statuses in the 500 range indicate that the server encountered an internal issue and was unable to fulfill the request.

All error responses include a JSON object with a code field and a message field. code contains a human-readable name for the HTTP status code and message contains a high-level description of the error. The error object may also contain additional error details which may be used by the client 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 and 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 will 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": "group not found"
  "details": [
    {
      "type": "ResourceInfo",
      "resource_type": "Group",
      "id": "4822738be6b7f658",
      "description": "group not found"
    }
  ],
}

Invalid Parameters Example

If the request body contains invalid parameters, you will 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": "group.display_name"
        }
      ],
    }
  ],
}

Tenants

A tenant represents an organization in the Beyond Identity Cloud. Tenants contain all data necessary for that organization to operate.

Retrieve an Existing Tenant

To retrieve an existing tenant, send a GET request to /v1/tenants/$TENANT_ID.

Authorizations:

BearerAuth

path Parameters

tenant_id

required

string

Example: 000176d94fd7b4d1

A unique identifier for a tenant.

Responses

Response samples

200
401
403
500

Content type

application/json

{"id": "000176d94fd7b4d1",
"display_name": "Test Tenant",
"create_time": "2022-01-28T12:00:02.423Z",
"update_time": "2022-04-19T15:17:21.186Z"
}

Patch a Tenant

To update only specific attributes of an existing tenant, send a PATCH request to /v1/tenants/$TENANT_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.

Authorizations:

BearerAuth

path Parameters

tenant_id

required

string

Example: 000176d94fd7b4d1

A unique identifier for a tenant.

Request Body schema: application/json

Updates to the specified tenant.

required

object (Tenant)

A tenant represents an organization in the Beyond Identity Cloud. Tenants contain all data necessary for that organization to operate.

display_name

string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/|*^%$#=~`!]*$

A human-readable name for the tenant. This name is used for display purposes.

Responses

Request samples

Payload

Content type

application/json

{"tenant": {"display_name": "Test Tenant"
}
}

Response samples

200
400
401
403
500

Content type

application/json

{"id": "000176d94fd7b4d1",
"display_name": "Test Tenant",
"create_time": "2022-01-28T12:00:02.423Z",
"update_time": "2022-04-19T15:17:21.186Z"
}

Realms

A realm is a unique administrative domain within a tenant. Realms may be used to define multiple development environments or for isolated administrative domains.

Create a New Realm

To create a realm, send a POST request to /v1/tenants/$TENANT_ID/realms. Values in the request body for read-only fields will be ignored.

Authorizations:

BearerAuth

path Parameters

tenant_id

required

string

Example: 000176d94fd7b4d1

A unique identifier for a tenant.

Request Body schema: application/json

required

object (Realm)

A realm is a unique administrative domain within a tenant. Realms may be used to define multiple development environments or for isolated administrative domains.

display_name

string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/|*^%$#=~`!]*$

A human-readable name for the realm. This name is used for display purposes.

Responses

Request samples

Payload

Content type

application/json

{"realm": {"display_name": "Test Realm"
}
}

Response samples

200
400
401
403
500

Content type

application/json

{"id": "19a95130480dfa79",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Realm",
"create_time": "2022-05-18T18:00:01.167Z",
"update_time": "2022-05-19T14:23:01.327Z"
}

List Realms for a Tenant

To list all realms for a tenant, send a GET request to /v1/tenants/$TENANT_ID/realms.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of realms in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id

required

string

Example: 000176d94fd7b4d1

A unique identifier for a tenant.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"realms": [{"id": "19a95130480dfa79",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Realm",
"create_time": "2022-05-18T18:00:01.167Z",
"update_time": "2022-05-19T14:23:01.327Z"
}
],
"total_size": 1
}

Retrieve an Existing Realm

To retrieve an existing realm, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "19a95130480dfa79",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Realm",
"create_time": "2022-05-18T18:00:01.167Z",
"update_time": "2022-05-19T14:23:01.327Z"
}

Patch a Realm

To update only specific attributes of an existing realm, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

Request Body schema: application/json

required

object (Realm)

A realm is a unique administrative domain within a tenant. Realms may be used to define multiple development environments or for isolated administrative domains.

display_name

string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/|*^%$#=~`!]*$

A human-readable name for the realm. This name is used for display purposes.

Responses

Request samples

Payload

Content type

application/json

{"realm": {"display_name": "Test Realm"
}
}

Response samples

Content type

application/json

{"id": "19a95130480dfa79",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Realm",
"create_time": "2022-05-18T18:00:01.167Z",
"update_time": "2022-05-19T14:23:01.327Z"
}

Delete a Realm

To delete a realm, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID. To be deleted, a realm must not have any identities, groups, or roles. All associated resources must first be deleted or you will receive a 409 error. A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

Responses

Response samples

401
403
404
409
500

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized"
}

Groups

A group is a logical collection of identities. Groups are commonly used as a predicate in a policy rule.

Create a New Group

To create a group, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups. Values in the request body for read-only fields will be ignored.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

Request Body schema: application/json

required

object (Group)

A group is a logical collection of identities. Groups are commonly used as a predicate in a policy rule.

display_name	string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A human-readable name for the group. This name is used for display purposes.
description	string <= 300 characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A free-form text field to describe a group.

Responses

Request samples

Payload

Content type

application/json

{"group": {"display_name": "Realm Administrators",
"description": "A group of realm administrators."
}
}

Response samples

Content type

application/json

{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"display_name": "Realm Administrators",
"description": "A group of realm administrators.",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}

List Groups for a Realm

To list all groups for a realm, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of groups in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

Content type

application/json

{"groups": [{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"display_name": "Realm Administrators",
"description": "A group of realm administrators.",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}
],
"total_size": 1
}

Retrieve an Existing Group

To retrieve an existing group, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
group_id required	string Example: 81490afab171aef0 A unique identifier for a group.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"display_name": "Realm Administrators",
"description": "A group of realm administrators.",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}

Patch a Group

To update only specific attributes of an existing group, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
group_id required	string Example: 81490afab171aef0 A unique identifier for a group.

Request Body schema: application/json

required

object (Group)

A group is a logical collection of identities. Groups are commonly used as a predicate in a policy rule.

display_name	string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A human-readable name for the group. This name is used for display purposes.
description	string <= 300 characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A free-form text field to describe a group.

Responses

Request samples

Payload

Content type

application/json

{"group": {"display_name": "Realm Administrators"
}
}

Response samples

Content type

application/json

{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"display_name": "Realm Administrators",
"description": "A group of realm administrators.",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}

Delete a Group

To delete a group, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID. To be deleted, a group must not have any members. Any existing members must first be deleted or you will receive a 409 error. A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
group_id required	string Example: 81490afab171aef0 A unique identifier for a group.

Responses

Response samples

401
403
404
409
500

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized"
}

Add Members to a Group

To add members to a group, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID:addMembers. The request must contain at least one and no more than 1000 identity IDs.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
group_id required	string Example: 81490afab171aef0 A unique identifier for a group.

Request Body schema: application/json

identity_ids

required

Array of strings [ 1 .. 1000 ] items

IDs of the identities to be added to the group.

Responses

Request samples

Payload

Content type

application/json

{"identity_ids": ["e372db224c06e850",
"3a28d4f28b57cc93"
]
}

Response samples

Content type

application/json

{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"display_name": "Realm Administrators",
"description": "A group of realm administrators.",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}

Delete Members from a Group

To delete members from a group, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID:deleteMembers. The request must contain at least one and no more than 1000 identity IDs.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
group_id required	string Example: 81490afab171aef0 A unique identifier for a group.

Request Body schema: application/json

identity_ids

required

Array of strings [ 1 .. 1000 ] items

IDs of the identities to be removed from the group.

Responses

Request samples

Payload

Content type

application/json

{"identity_ids": ["e372db224c06e850",
"3a28d4f28b57cc93"
]
}

Response samples

Content type

application/json

{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"display_name": "Realm Administrators",
"description": "A group of realm administrators.",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}

List Members for a Group

To list members belonging to a group, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID:listMembers.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of members in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
group_id required	string Example: 81490afab171aef0 A unique identifier for a group.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

Content type

application/json

{"identities": [{"id": "e372db224c06e850",
"realm_id": "8f5bec58229e6f29",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Identity",
"create_time": "2022-04-12T05:53:07.119Z",
"update_time": "2022-06-16T14:31:03.770Z",
"traits": {"type": "traits_v0",
"username": "test",
"primary_email_address": "test@example.com"
}
}
],
"total_size": 1
}

List Role Memberships for a Group

To list the roles to which a group is assigned, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID:listRoles.

The request must include the resource_server_id query parameter specifying the resource server on which to filter the roles. If the specified resource server does not exist, you will receive a 409 error.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of roles in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
group_id required	string Example: 81490afab171aef0 A unique identifier for a group.

query Parameters

resource_server_id	string non-empty The unique identifier of the resource server used to filter roles.
page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

Content type

application/json

{"roles": [{"id": "fb785d40cbe4fc0d",
"resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
"realm_id": "bb26e0e8ecdef843",
"tenant_id": "00010036778ce59f",
"description": "Help Desk",
"display_name": "Customer support personnel.",
"create_time": "2023-02-14T18:18:58.332Z",
"update_time": "2023-02-14T18:18:58.332Z"
}
],
"total_size": 1
}

Identities

An identity is a unique identifier that may be used by an end-user to gain access governed by Beyond Identity.

Create a New Identity

To create an identity, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities. Values in the request body for read-only fields will be ignored. If the request conflicts with an existing resource, you will receive a 409 error.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

Request Body schema: application/json

required

object (Identity)

An identity is a unique identifier that may be used by an end-user to gain access governed by Beyond Identity.

display_name	string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A human-readable name for the identity. This name is used for display purposes.
status	string Indicator for the identity's administrative status. If 'active', the identity is able to generate passkeys and login. If 'suspended', the identity is unable to generate passkeys or login.
	any A collection of properties to describe an identity. All traits contain a `type` key which describes the specific traits schema.

Responses

Request samples

Payload

Content type

application/json

{"identity": {"display_name": "Test Identity",
"traits": {"type": "traits_v0",
"username": "test",
"primary_email_address": "test@example.com"
}
}
}

Response samples

Content type

application/json

{"id": "e372db224c06e850",
"realm_id": "8f5bec58229e6f29",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Identity",
"create_time": "2022-04-12T05:53:07.119Z",
"update_time": "2022-06-16T14:31:03.770Z",
"traits": {"type": "traits_v0",
"username": "test",
"primary_email_address": "test@example.com"
}
}

List Identities for a Realm

To list identities for a realm, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities.

The response will only contain identities matching the filter in the request. If no filter is provided, the request will match all identities in the realm. Currently, the only supported filter is traits.username eq "$USERNAME".

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of identities in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The filter is also maintained by the page token but it may not be overridden. If specified, the request filter must match the filter maintained by the page token, otherwise you will receive a 400 error. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

query Parameters

filter	string Filter to constrain the response. The response will only include resources matching this filter. Filters follow the SCIM grammar from RFC-7644 Section 3.4.2.2.
page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

Content type

application/json

{"identities": [{"id": "e372db224c06e850",
"realm_id": "8f5bec58229e6f29",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Identity",
"create_time": "2022-04-12T05:53:07.119Z",
"update_time": "2022-06-16T14:31:03.770Z",
"traits": {"type": "traits_v0",
"username": "test",
"primary_email_address": "test@example.com"
}
}
],
"total_size": 1
}

Retrieve an Existing Identity

To retrieve an existing identity, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "e372db224c06e850",
"realm_id": "8f5bec58229e6f29",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Identity",
"create_time": "2022-04-12T05:53:07.119Z",
"update_time": "2022-06-16T14:31:03.770Z",
"traits": {"type": "traits_v0",
"username": "test",
"primary_email_address": "test@example.com"
}
}

Patch an Identity

To update only specific attributes of an existing identity, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged. If the request conflicts with an existing resource, you will receive a 409 error.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.

Request Body schema: application/json

required

object (Identity)

An identity is a unique identifier that may be used by an end-user to gain access governed by Beyond Identity.

display_name	string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A human-readable name for the identity. This name is used for display purposes.
status	string Indicator for the identity's administrative status. If 'active', the identity is able to generate passkeys and login. If 'suspended', the identity is unable to generate passkeys or login.
	any A collection of properties to describe an identity. All traits contain a `type` key which describes the specific traits schema.

Responses

Request samples

Payload

Content type

application/json

{"identity": {"display_name": "Test Identity",
"traits": {"type": "traits_v0",
"primary_email_address": "test@example.com"
}
}
}

Response samples

Content type

application/json

{"id": "e372db224c06e850",
"realm_id": "8f5bec58229e6f29",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Identity",
"create_time": "2022-04-12T05:53:07.119Z",
"update_time": "2022-06-16T14:31:03.770Z",
"traits": {"type": "traits_v0",
"username": "test",
"primary_email_address": "test@example.com"
}
}

Delete an Identity

To delete an identity, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID. To be deleted, an identity must not be a member of any groups or roles. The identity must must first be removed from all groups and roles or you will receive a 409 error. A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.

Responses

Response samples

401
403
404
409
500

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized"
}

List Group Memberships for an Identity

To list the groups to which an identity belongs, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID:listGroups.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of groups in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

Content type

application/json

{"groups": [{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"display_name": "Realm Administrators",
"description": "A group of realm administrators.",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}
],
"total_size": 1
}

List Role Memberships for an Identity

To list the roles to which an identity is assigned, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID:listRoles.

The request must include the resource_server_id query parameter specifying the resource server on which to filter the roles. If the specified resource server does not exist, you will receive a 409 error.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of roles in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.

query Parameters

resource_server_id	string non-empty The unique identifier of the resource server used to filter roles.
page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

Content type

application/json

{"roles": [{"id": "fb785d40cbe4fc0d",
"resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
"realm_id": "bb26e0e8ecdef843",
"tenant_id": "00010036778ce59f",
"description": "Help Desk",
"display_name": "Customer support personnel.",
"create_time": "2023-02-14T18:18:58.332Z",
"update_time": "2023-02-14T18:18:58.332Z"
}
],
"total_size": 1
}

Credentials

A credential is also known as a passkey. This is the public-private key pair that belongs to an identity.

List Credentials for an Identity

To list all credentials for an identity, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credentials. $IDENTITY_ID may be a wildcard (-) to request all credentials across all identities within the realm.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of credentials in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"credentials": [{"id": "81490afab171aef0",
"identity_id": "e85de356dc78843a",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"state": "ACTIVE",
"csr_type": "JWT",
"jwk_json": "{\"crv\":\"P-256\",\"kty\":\"EC\",\"x\":\"2MRhz05PJPq3BUfB18AT3HqgWEkI3VpWUg1MWi8rz1g\",\"y\":\"YtvLYwGEqYQaoDVok2fVziJT4fu7DFPz3hy96FTAelQ\"}",
"jwk_thumbprint": "UW-uVNL0mP1vcLjHrTBxibNgCEe_PD0HIsE3FrbYjPA=",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}
],
"total_size": 1
}

Retrieve an Existing Credential

To retrieve an existing credential, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credentials/$CREDENTIAL_ID.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.
credential_id required	string Example: b5a31610800dda18 A unique identifier for a credential.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "81490afab171aef0",
"identity_id": "e85de356dc78843a",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"state": "ACTIVE",
"csr_type": "JWT",
"jwk_json": "{\"crv\":\"P-256\",\"kty\":\"EC\",\"x\":\"2MRhz05PJPq3BUfB18AT3HqgWEkI3VpWUg1MWi8rz1g\",\"y\":\"YtvLYwGEqYQaoDVok2fVziJT4fu7DFPz3hy96FTAelQ\"}",
"jwk_thumbprint": "UW-uVNL0mP1vcLjHrTBxibNgCEe_PD0HIsE3FrbYjPA=",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}

Revoke a Credential

To revoke a credential, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credentials/$CREDENTIAL_ID:revoke.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.
credential_id required	string Example: b5a31610800dda18 A unique identifier for a credential.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "81490afab171aef0",
"identity_id": "e85de356dc78843a",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"state": "ACTIVE",
"csr_type": "JWT",
"jwk_json": "{\"crv\":\"P-256\",\"kty\":\"EC\",\"x\":\"2MRhz05PJPq3BUfB18AT3HqgWEkI3VpWUg1MWi8rz1g\",\"y\":\"YtvLYwGEqYQaoDVok2fVziJT4fu7DFPz3hy96FTAelQ\"}",
"jwk_thumbprint": "UW-uVNL0mP1vcLjHrTBxibNgCEe_PD0HIsE3FrbYjPA=",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}

Credential Binding Jobs

A credential binding job defines the state of binding a new credential to an identity. The state includes creation of the credential binding job to delivery of the credential binding method to completion of the credential binding.

Create a New Credential Binding Job

To create an identity, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credential-binding-jobs. Values in the request body for read-only fields will be ignored.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.

Request Body schema: application/json

Credential binding job to be created.

required

object (CredentialBindingJob)

A credential binding job defines the state of binding a new credential to an identity. The state includes creation of the credential binding job to delivery of the credential binding method to completion of the credential binding.

credential_id	string A unique identifier for the credential that was bound via the credential binding job. This field will only be populated if the credential binding job has successfully been used to bind a credential to an identity.
delivery_method	string Enum: "RETURN" "EMAIL" The method by which a credential binding link is delivered to the target authenticator or identity. The value `RETURN` indicates that a credential binding link will be returned to the caller upon creation of the credential binding job. The value `EMAIL` indicates that a credential binding link will be sent to the email address associated with the identity.
post_binding_redirect_uri	string The URI to which the caller will be redirected after successfully binding a credential to an identity. This field is optional. If not specified, the authenticator will not attempt to redirect to a new location after binding.
authenticator_config_id	string The ID of the authenticator configuration to be used to build the credential binding job. This field is immutable.

Responses

Request samples

Payload

Content type

application/json

{"job": {"delivery_method": "RETURN",
"post_binding_redirect_uri": "http://example.com/callback",
"authenticator_config_id": "67bb0acf12e5c899"
}
}

Response samples

Content type

application/json

Example

Delivery Method Return

{"credential_binding_job": {"id": "c4fc2d753ca22b14",
"realm_id": "cdf4862dc4d49791",
"tenant_id": "000183a77dd50fa9",
"identity_id": "87fabad6956c6d4b",
"delivery_method": "RETURN",
"state": "LINK_SENT",
"post_binding_redirect_uri": "http://example.com/callback",
"authenticator_config_id": "67bb0acf12e5c899",
"expire_time": "2022-03-21T03:42:52.905Z",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-03-15T05:55:23.823Z"
},
"credential_binding_link": "http://example.com/v1/tenants/000183a77dd50fa9/realms/cdf4862dc4d49791/identities/87fabad6956c6d4b/credential-binding-jobs/c4fc2d753ca22b14:invokeAuthenticator?token=1St9IKIIrYyQ8sOSeuk5UkbLKnBJhuD4I7nWIqt-BNANDEFS-XVuOHxB7TFdZcRm"
}

List Credential Binding Jobs for an Identity

To list all credential binding jobs for an identity, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credential-binding-jobs. $IDENTITY_ID may be a wildcard (-) to request all credential binding jobs across all identities within the realm.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of credential binding jobs in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"credential_binding_jobs": [{"id": "81490afab171aef0",
"identity_id": "e85de356dc78843a",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"credential_id": "9802966246819b35",
"delivery_method": "EMAIL",
"state": "COMPLETE",
"post_binding_redirect_uri": "http://example.com/callback",
"authenticator_config_id": "67bb0acf12e5c899",
"expire_time": "2022-03-21T03:42:52.905Z",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-03-15T05:55:23.823Z"
}
],
"total_size": 1
}

Retrieve an Existing Credential Binding Job

To retrieve an existing credential binding job, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credential-binding-jobs/$CREDENTIAL_BINDING_JOB_ID`.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
identity_id required	string Example: e372db224c06e850 A unique identifier for an identity.
credential_binding_job_id required	string Example: 5c4137af5e70413a A unique identifier for a credential binding job.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "81490afab171aef0",
"identity_id": "e85de356dc78843a",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"credential_id": "9802966246819b35",
"delivery_method": "EMAIL",
"state": "COMPLETE",
"post_binding_redirect_uri": "http://example.com/callback",
"authenticator_config_id": "67bb0acf12e5c899",
"expire_time": "2022-03-21T03:42:52.905Z",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-03-15T05:55:23.823Z"
}

Themes

A theme is a collection of configurable assets that unifies the end user login experience with your brand and products. It is primarily used to change the styling of the credential binding email.

Create a New Theme

To create a theme, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/themes/$THEME_ID. Values in the request body for read-only fields will be ignored. All non-read-only fields are optional and will be populated with defaults if unspecified. Currently, each realm only supports a single theme. If a theme already exists for the realm, you will receive a 409 error.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

Request Body schema: application/json

Theme to be created.

object (Theme)

A theme is a collection of configurable assets that unifies the end user login experience with your brand and products. It is primarily used to change the styling of the credential binding email.

email_realm_name	string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ Realm name that is used in email templates.
logo_url_light	string URL for resolving the logo image for light mode.
logo_url_dark	string URL for resolving the logo image for dark mode.
support_url	string <url> URL for the customer support portal.
button_color	string Hexadecimal color code to use for buttons.
button_text_color	string Hexadecimal color code to use for button text.

Responses

Request samples

Payload

Content type

application/json

{"theme": {"email_realm_name": "Realm Administrators",
"logo_url_light": "https://example.com/logo_url_light.png",
"logo_url_dark": "https://example.com/logo_url_dark.png",
"support_url": "https://example.com/support",
"button_color": "#4673D3",
"button_text_color": "#FFFFFF"
}
}

Response samples

Content type

application/json

{"id": "88ef08fb-c3f9-44e2-b174-fbb239e1dc47",
"tenant_id": "f36448f2ff094881",
"realm_id": "aa6aabe6989bc4a5",
"email_realm_name": "Realm Administrators",
"logo_url_light": "https://example.com/logo_url_light.png",
"logo_url_dark": "https://example.com/logo_url_dark.png",
"support_url": "https://example.com/support",
"create_time": "2022-07-28T18:00:00.000Z",
"button_color": "#4673D3",
"button_text_color": "#FFFFFF"
}

Get the Active Theme

To retrieve the active theme for a realm, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/themes/active. If the realm has not specified the active theme, a default theme will be returned.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "88ef08fb-c3f9-44e2-b174-fbb239e1dc47",
"tenant_id": "f36448f2ff094881",
"realm_id": "aa6aabe6989bc4a5",
"email_realm_name": "Realm Administrators",
"logo_url_light": "https://example.com/logo_url_light.png",
"logo_url_dark": "https://example.com/logo_url_dark.png",
"support_url": "https://example.com/support",
"create_time": "2022-07-28T18:00:00.000Z",
"button_color": "#4673D3",
"button_text_color": "#FFFFFF"
}

Retrive an Existing Theme

To retrieve an existing theme, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/themes/$THEME_ID.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
theme_id required	string Example: 88ef08fb-c3f9-44e2-b174-fbb239e1dc47 A unique identifier for a theme.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "88ef08fb-c3f9-44e2-b174-fbb239e1dc47",
"tenant_id": "f36448f2ff094881",
"realm_id": "aa6aabe6989bc4a5",
"email_realm_name": "Realm Administrators",
"logo_url_light": "https://example.com/logo_url_light.png",
"logo_url_dark": "https://example.com/logo_url_dark.png",
"support_url": "https://example.com/support",
"create_time": "2022-07-28T18:00:00.000Z",
"button_color": "#4673D3",
"button_text_color": "#FFFFFF"
}

Patch a Theme

To update only specific attributes of an existing theme, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/themes/$THEME_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
theme_id required	string Example: 88ef08fb-c3f9-44e2-b174-fbb239e1dc47 A unique identifier for a theme.

Request Body schema: application/json

Theme to be updated.

object (Theme)

A theme is a collection of configurable assets that unifies the end user login experience with your brand and products. It is primarily used to change the styling of the credential binding email.

email_realm_name	string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ Realm name that is used in email templates.
logo_url_light	string URL for resolving the logo image for light mode.
logo_url_dark	string URL for resolving the logo image for dark mode.
support_url	string <url> URL for the customer support portal.
button_color	string Hexadecimal color code to use for buttons.
button_text_color	string Hexadecimal color code to use for button text.

Responses

Request samples

Payload

Content type

application/json

{"theme": {"email_realm_name": "Realm Administrators"
}
}

Response samples

Content type

application/json

{"id": "88ef08fb-c3f9-44e2-b174-fbb239e1dc47",
"tenant_id": "f36448f2ff094881",
"realm_id": "aa6aabe6989bc4a5",
"email_realm_name": "Realm Administrators",
"logo_url_light": "https://example.com/logo_url_light.png",
"logo_url_dark": "https://example.com/logo_url_dark.png",
"support_url": "https://example.com/support",
"create_time": "2022-07-28T18:00:00.000Z",
"button_color": "#4673D3",
"button_text_color": "#FFFFFF"
}

Applications

An application represents a client application that uses Beyond Identity for authentication. This could be a native app, a single-page application, regular web application, or machine-to-machine application credentials.

Create a New Application

To create an application, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/applications. Values in the request body for read-only fields will be ignored. At present, there are only two supported protocol types for applications, oauth2 and oidc.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

Request Body schema: application/json

required

object (Application)

An application represents a client application that uses Beyond Identity for authentication. This could be a native app, a single-page application, regular web application, or machine-to-machine application credentials.

resource_server_id	string A unique identifier for the application's resource server. At present, the only available resource server is for the Beyond Identity Management API. Referencing this resource server from an application will allow that application to grant access to Beyond Identity's APIs. When not present, this application may provide authentication (identity) but not authorization (access).
authenticator_config_id	string A unique identifier for the application's authenticator configuration. This field is unused for `oidc` and `oauth2` applications when `grant_type=client_credentials`.
display_name	string A human-readable name for the application. This name is used for display purposes.
	OAuth 2.0 (object) or OIDC (object) Represents an application protocol configuration.

Responses

Request samples

Payload

Content type

application/json

{"application": {"display_name": "Pet Application",
"resource_server_id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
"protocol_config": {"type": "oidc",
"allowed_scopes": ["pets:read",
"pets:write"
],
"confidentiality": "confidential",
"token_endpoint_auth_method": "client_secret_post",
"grant_type": ["authorization_code"
],
"redirect_uris": ["https://auth.mypetapp.com/callback"
],
"token_configuration": {"subject_field": "id",
"expires_after": 86400,
"token_signing_algorithm": "RS256"
},
"pkce": "disabled",
"token_format": "self_contained"
}
}
}

Response samples

Content type

application/json

{"id": "38833c36-6f47-4992-9329-ea0a00915137",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"resource_server_id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
"display_name": "Pet Application",
"is_managed": false,
"protocol_config": {"type": "oidc",
"allowed_scopes": ["pets:read",
"pets:write"
],
"client_id": "AYYNcuOSpfqIf33JeegCzDIT",
"client_secret": "wWD4mPzdsjms1LPekQSo0v9scOHLWy5wmMtKAR2JNhJPAKXv",
"confidentiality": "confidential",
"token_endpoint_auth_method": "client_secret_post",
"grant_type": ["authorization_code"
],
"redirect_uris": ["https://auth.mypetapp.com/callback"
],
"token_configuration": {"subject_field": "id",
"expires_after": 86400,
"token_signing_algorithm": "RS256"
},
"pkce": "disabled",
"token_format": "self_contained"
}
}

List Applications for a Realm

To list all applications for a realm, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/applications.

The response will contain at most 100 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 100 items. There is no defined ordering of the list of applications in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.

Responses

Response samples

Content type

application/json

{"applications": [{"id": "38833c36-6f47-4992-9329-ea0a00915137",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"resource_server_id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
"display_name": "Pet Application",
"is_managed": false,
"protocol_config": {"type": "oidc",
"allowed_scopes": ["pets:read",
"pets:write"
],
"client_id": "AYYNcuOSpfqIf33JeegCzDIT",
"client_secret": "wWD4mPzdsjms1LPekQSo0v9scOHLWy5wmMtKAR2JNhJPAKXv",
"confidentiality": "confidential",
"token_endpoint_auth_method": "client_secret_post",
"grant_type": ["authorization_code"
],
"redirect_uris": ["https://auth.mypetapp.com/callback"
],
"token_configuration": {"subject_field": "id",
"expires_after": 86400,
"token_signing_algorithm": "RS256"
},
"pkce": "disabled",
"token_format": "self_contained"
}
}
],
"total_size": 1
}

Retrieve an Existing Application

To retrieve an existing application, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/applications/$APPLICATION_ID.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
application_id required	string Example: 38833c36-6f47-4992-9329-ea0a00915137 A unique identifier for an application.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "38833c36-6f47-4992-9329-ea0a00915137",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"resource_server_id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
"display_name": "Pet Application",
"is_managed": false,
"protocol_config": {"type": "oidc",
"allowed_scopes": ["pets:read",
"pets:write"
],
"client_id": "AYYNcuOSpfqIf33JeegCzDIT",
"client_secret": "wWD4mPzdsjms1LPekQSo0v9scOHLWy5wmMtKAR2JNhJPAKXv",
"confidentiality": "confidential",
"token_endpoint_auth_method": "client_secret_post",
"grant_type": ["authorization_code"
],
"redirect_uris": ["https://auth.mypetapp.com/callback"
],
"token_configuration": {"subject_field": "id",
"expires_after": 86400,
"token_signing_algorithm": "RS256"
},
"pkce": "disabled",
"token_format": "self_contained"
}
}

Patch an Application

To update only specific attributes of an existing application, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/applications/$APPLICATION_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
application_id required	string Example: 38833c36-6f47-4992-9329-ea0a00915137 A unique identifier for an application.

Request Body schema: application/json

required

object (Application)

An application represents a client application that uses Beyond Identity for authentication. This could be a native app, a single-page application, regular web application, or machine-to-machine application credentials.

resource_server_id	string A unique identifier for the application's resource server. At present, the only available resource server is for the Beyond Identity Management API. Referencing this resource server from an application will allow that application to grant access to Beyond Identity's APIs. When not present, this application may provide authentication (identity) but not authorization (access).
authenticator_config_id	string A unique identifier for the application's authenticator configuration. This field is unused for `oidc` and `oauth2` applications when `grant_type=client_credentials`.
display_name	string A human-readable name for the application. This name is used for display purposes.
	OAuth 2.0 (object) or OIDC (object) Represents an application protocol configuration.

Responses

Request samples

Payload

Content type

application/json

{"application": {"display_name": "Pet Application"
}
}

Response samples

Content type

application/json

{"id": "38833c36-6f47-4992-9329-ea0a00915137",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"resource_server_id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
"display_name": "Pet Application",
"is_managed": false,
"protocol_config": {"type": "oidc",
"allowed_scopes": ["pets:read",
"pets:write"
],
"client_id": "AYYNcuOSpfqIf33JeegCzDIT",
"client_secret": "wWD4mPzdsjms1LPekQSo0v9scOHLWy5wmMtKAR2JNhJPAKXv",
"confidentiality": "confidential",
"token_endpoint_auth_method": "client_secret_post",
"grant_type": ["authorization_code"
],
"redirect_uris": ["https://auth.mypetapp.com/callback"
],
"token_configuration": {"subject_field": "id",
"expires_after": 86400,
"token_signing_algorithm": "RS256"
},
"pkce": "disabled",
"token_format": "self_contained"
}
}

Delete an Application

To delete an application, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/applications/$APPLICATION_ID. A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
application_id required	string Example: 38833c36-6f47-4992-9329-ea0a00915137 A unique identifier for an application.

Responses

Response samples

401
403
404
500

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized"
}

Authenticator Configurations

A authenticator configuration prescribes how an end user may authenticate themselves to Beyond Identity. Beyond Identity provides a Hosted Web Authenticator which will work out-of-the-box, as well as SDKs that can be embedded into an end user application.

Create a New Authenticator Configuration

To create an authenticator configuration, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/authenticator-configs. Values in the request body for read-only fields will be ignored.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

Request Body schema: application/json

required

object (Authenticator Configuration)

Representation of an authenticator configuration. This prescribes how an identity may authenticate themselves with Beyond Identity.

display_name	string A human-readable name for the authenticator configuration. This name is used for display purposes.
	Embedded SDK Authenticator (object) or Hosted Web Authenticator (object) An object specifying the settings for the supported authenticator type.

Responses

Request samples

Payload

Content type

application/json

{"authenticator_config": {"display_name": "Pet Authenticator Configuration",
"config": {"type": "embedded",
"invoke_url": "http://localhost:8092",
"trusted_origins": ["http://localhost:8092"
]
}
}
}

Response samples

Content type

application/json

Example

Success Embedded

{"id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"display_name": "Pet Authenticator Configuration",
"config": {"type": "embedded",
"invoke_url": "http://localhost:8092",
"invocation_type": "automatic",
"trusted_origins": ["http://localhost:8092"
],
"authentication_methods": [{"type": "email_one_time_password"
},
{"type": "software_passkey"
},
{"type": "webauthn_passkey"
}
]
}
}

List Authenticator Configurations for a Realm

To list all authenticator configurations for a realm, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/authenticator-configs.

The response will contain at most 100 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 100 items. There is no defined ordering of the list of authenticator configurations in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.

Responses

Response samples

Content type

application/json

{"authenticator_configs": [{"id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"display_name": "Pet Authenticator Configuration",
"config": {"invoke_url": "http://localhost:8092",
"invocation_type": "automatic",
"trusted_origins": ["http://localhost:8092"
],
"type": "embedded"
}
}
],
"total_size": 1
}

Retrieve an Existing Authenticator Configuration

To retrieve an existing authenticator configuration, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/authenticator-configs/$AUTHENTICATOR_CONFIG_ID.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
authenticator_config_id required	string Example: 73731b7f-eb76-4143-9b4b-81a720385f5a A unique identifier for an authenticator configuration.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"display_name": "Pet Authenticator Configuration",
"config": {"type": "embedded",
"invoke_url": "http://localhost:8092",
"invocation_type": "automatic",
"trusted_origins": ["http://localhost:8092"
],
"authentication_methods": [{"type": "email_one_time_password"
},
{"type": "software_passkey"
},
{"type": "webauthn_passkey"
}
]
}
}

Patch an Authenticator Configuration

To update only specific attributes of an existing authenticator configuration, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/authenticator-configs/$AUTHENTICATOR_CONFIG_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
authenticator_config_id required	string Example: 73731b7f-eb76-4143-9b4b-81a720385f5a A unique identifier for an authenticator configuration.

Request Body schema: application/json

required

object (Authenticator Configuration)

Representation of an authenticator configuration. This prescribes how an identity may authenticate themselves with Beyond Identity.

display_name	string A human-readable name for the authenticator configuration. This name is used for display purposes.
	Embedded SDK Authenticator (object) or Hosted Web Authenticator (object) An object specifying the settings for the supported authenticator type.

Responses

Request samples

Payload

Content type

application/json

{"authenticator_config": {"display_name": "Pet Authenticator Configuration",
"config": {"invoke_url": "http://localhost:8092"
}
}
}

Response samples

Content type

application/json

Example

Success Embedded

{"id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"display_name": "Pet Authenticator Configuration",
"config": {"type": "embedded",
"invoke_url": "http://localhost:8092",
"invocation_type": "automatic",
"trusted_origins": ["http://localhost:8092"
],
"authentication_methods": [{"type": "email_one_time_password"
},
{"type": "software_passkey"
},
{"type": "webauthn_passkey"
}
]
}
}

Delete an Authenticator Configuration

To delete an authenticator configuration, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/authenticator-configs/$AUTHENTICATOR_CONFIG_ID. A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
authenticator_config_id required	string Example: 73731b7f-eb76-4143-9b4b-81a720385f5a A unique identifier for an authenticator configuration.

Responses

Response samples

401
403
404
500

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized"
}

Resource Servers

A resource server represents an API server that hosts a set of protected resources and is capable of accepting and responding to protected resource requests using access tokens. Clients can enable these APIs to be consumed from authorized applications.

Create a New Resource Server

To create a resource server, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers. Values in the request body for read-only fields will be ignored.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

Request Body schema: application/json

required

object (Resource Server)

A resource server represents an API server that hosts a set of protected resources and is capable of accepting and responding to protected resource requests using access tokens. Clients can enable these APIs to be consumed from authorized applications.

display_name	string A human-readable name for the resource server. This name is used for display purposes.
identifier	string The identifier of this resource server entity. This value should be unique per realm and is often presented as a URI, as it should be a unique identifier for an API to which access is being gated. This identifier will be returned in the `audience` claim of all tokens minted that provide access to scopes owned by this resource server. The client is responsible for validating tokens are intended for them via this `audience` claim. Tokens minted for the Beyond Identity Management API will use the audience `beyondidentity`, which is reserved and may not be used for any other resource servers.
scopes	Array of strings The list of scopes supported by this resource server. For the Beyond Identity Management API, this will include scopes for all publicly available endpoints. Note that applications may not provide access to scopes that are not defined on a resource server that they reference; this is the superset of all allowable application scopes in a given realm.

Responses

Request samples

Payload

Content type

application/json

{"resource_server": {"display_name": "Pet API",
"identifier": "https://api.mypetapp.com",
"scopes": ["pets:read",
"pets:write"
]
}
}

Response samples

Content type

application/json

{"id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"display_name": "Pet API",
"is_managed": false,
"identifier": "https://api.mypetapp.com",
"scopes": ["pets:read",
"pets:write"
]
}

List Resource Servers For a Realm

To list all resource servers for a realm, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers.

The response will contain at most 100 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 100 items. There is no defined ordering of the list of resource servers in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.

Responses

Response samples

Content type

application/json

{"resource_servers": [{"id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"display_name": "Pet API",
"is_managed": false,
"identifier": "https://api.mypetapp.com",
"scopes": ["pets:read",
"pets:write"
]
}
],
"total_size": 1
}

Retrieve an Existing Resource Server

To retrieve an existing resource server, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"display_name": "Pet API",
"is_managed": false,
"identifier": "https://api.mypetapp.com",
"scopes": ["pets:read",
"pets:write"
]
}

Patch a Resource Server

To update only specific attributes of an existing resource server, send a a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.

Scopes that are removed from a resource server will be asynchronously removed from all roles associated with the resource server.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.

Request Body schema: application/json

required

object (Resource Server)

A resource server represents an API server that hosts a set of protected resources and is capable of accepting and responding to protected resource requests using access tokens. Clients can enable these APIs to be consumed from authorized applications.

display_name	string A human-readable name for the resource server. This name is used for display purposes.
identifier	string The identifier of this resource server entity. This value should be unique per realm and is often presented as a URI, as it should be a unique identifier for an API to which access is being gated. This identifier will be returned in the `audience` claim of all tokens minted that provide access to scopes owned by this resource server. The client is responsible for validating tokens are intended for them via this `audience` claim. Tokens minted for the Beyond Identity Management API will use the audience `beyondidentity`, which is reserved and may not be used for any other resource servers.
scopes	Array of strings The list of scopes supported by this resource server. For the Beyond Identity Management API, this will include scopes for all publicly available endpoints. Note that applications may not provide access to scopes that are not defined on a resource server that they reference; this is the superset of all allowable application scopes in a given realm.

Responses

Request samples

Payload

Content type

application/json

{"resource_server": {"display_name": "Pet API"
}
}

Response samples

Content type

application/json

{"id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
"realm_id": "caf2ff640497591a",
"tenant_id": "00011f1183c67b69",
"display_name": "Pet API",
"is_managed": false,
"identifier": "https://api.mypetapp.com",
"scopes": ["pets:read",
"pets:write"
]
}

Delete a Resource Server

To delete a resource server, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID. A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.

Responses

Response samples

401
403
404
500

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized"
}

Roles

Create a New Role

To create a role, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles. Values in the request body for read-only fields will be ignored.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.

Request Body schema: application/json

Role to be created.

object (Role)

A role is a logical collection of scopes. Roles are commonly used to limit access control.

The scopes belonging to a role are limited to its associated resource server. However, note that the resource server may change independently of the role. If scopes are added to or removed from a resource server, its associated roles must be manually updated using the AddRoleScopes or DeleteRoleScopes methods.

display_name	string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A human-readable name for the role. This name is used for display purposes.
description	string <= 300 characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A free-form text field to describe a role.

Responses

Request samples

Payload

Content type

application/json

{"role": {"display_name": "Help Desk",
"description": "Customer support personnel."
}
}

Response samples

Content type

application/json

{"id": "fb785d40cbe4fc0d",
"resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
"realm_id": "bb26e0e8ecdef843",
"tenant_id": "00010036778ce59f",
"description": "Help Desk",
"display_name": "Customer support personnel.",
"create_time": "2023-02-14T18:18:58.332Z",
"update_time": "2023-02-14T18:18:58.332Z"
}

List Roles for a Resource Server

To list all roles for a resource server, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of roles in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

Content type

application/json

{"roles": [{"id": "fb785d40cbe4fc0d",
"resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
"realm_id": "bb26e0e8ecdef843",
"tenant_id": "00010036778ce59f",
"description": "Help Desk",
"display_name": "Customer support personnel.",
"create_time": "2023-02-14T18:18:58.332Z",
"update_time": "2023-02-14T18:18:58.332Z"
}
],
"total_size": 1
}

Retrieve an Existing Role

To retrieve an existing role, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.
role_id required	string Example: fb785d40cbe4fc0d A unique identifier for a role.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "fb785d40cbe4fc0d",
"resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
"realm_id": "bb26e0e8ecdef843",
"tenant_id": "00010036778ce59f",
"description": "Help Desk",
"display_name": "Customer support personnel.",
"create_time": "2023-02-14T18:18:58.332Z",
"update_time": "2023-02-14T18:18:58.332Z"
}

Patch a Role

To update only specific attributes of an existing role, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.
role_id required	string Example: fb785d40cbe4fc0d A unique identifier for a role.

Request Body schema: application/json

Updates to the specified role.

required

object (Role)

A role is a logical collection of scopes. Roles are commonly used to limit access control.

The scopes belonging to a role are limited to its associated resource server. However, note that the resource server may change independently of the role. If scopes are added to or removed from a resource server, its associated roles must be manually updated using the AddRoleScopes or DeleteRoleScopes methods.

display_name	string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A human-readable name for the role. This name is used for display purposes.
description	string <= 300 characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A free-form text field to describe a role.

Responses

Request samples

Payload

Content type

application/json

{"role": {"display_name": "Help Desk"
}
}

Response samples

Content type

application/json

{"id": "fb785d40cbe4fc0d",
"resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
"realm_id": "bb26e0e8ecdef843",
"tenant_id": "00010036778ce59f",
"description": "Help Desk",
"display_name": "Customer support personnel.",
"create_time": "2023-02-14T18:18:58.332Z",
"update_time": "2023-02-14T18:18:58.332Z"
}

Delete a Role

To delete a role, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID. To be deleted, a role must not have any scopes or members. Any existing scopes and members must first be deleted or you will receive a 409 error. A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.
role_id required	string Example: fb785d40cbe4fc0d A unique identifier for a role.

Responses

Response samples

401
403
404
409
500

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized"
}

Assign Members to a Role

To assign members to a role, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:addMembers. The request must contain at least one group ID or identity ID and must not contain more than 1000 group IDs or 1000 identity IDs.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.
role_id required	string Example: fb785d40cbe4fc0d A unique identifier for a role.

Request Body schema: application/json

group_ids	Array of strings [ 1 .. 1000 ] items IDs of the groups to be assigned to the role.
identity_ids	Array of strings [ 1 .. 1000 ] items IDs of the identities to be assigned to the role.

Responses

Request samples

Payload

Content type

application/json

{"group_ids": ["e372db224c06e850"
],
"identity_ids": ["3a28d4f28b57cc93"
]
}

Response samples

Content type

application/json

{"id": "fb785d40cbe4fc0d",
"resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
"realm_id": "bb26e0e8ecdef843",
"tenant_id": "00010036778ce59f",
"description": "Help Desk",
"display_name": "Customer support personnel.",
"create_time": "2023-02-14T18:18:58.332Z",
"update_time": "2023-02-14T18:18:58.332Z"
}

Unassign Members from a Role

To unassign members from a role, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:deleteMembers. The request must contain at least one group ID or identity ID and must not contain more than 1000 group IDs or 1000 identity IDs.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.
role_id required	string Example: fb785d40cbe4fc0d A unique identifier for a role.

Request Body schema: application/json

group_ids	Array of strings [ 1 .. 1000 ] items IDs of the groups to be unassigned from the role.
identity_ids	Array of strings [ 1 .. 1000 ] items IDs of the identities to be unassigned from the role.

Responses

Request samples

Payload

Content type

application/json

{"group_ids": ["e372db224c06e850"
],
"identity_ids": ["3a28d4f28b57cc93"
]
}

Response samples

Content type

application/json

{"id": "fb785d40cbe4fc0d",
"resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
"realm_id": "bb26e0e8ecdef843",
"tenant_id": "00010036778ce59f",
"description": "Help Desk",
"display_name": "Customer support personnel.",
"create_time": "2023-02-14T18:18:58.332Z",
"update_time": "2023-02-14T18:18:58.332Z"
}

List Members for a Role

To list members assigned to a role, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:listMembers.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of members in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.
role_id required	string Example: fb785d40cbe4fc0d A unique identifier for a role.

query Parameters

groups_page_size	integer <uint32> >= 0 Number of groups returned per page for ListRoleMembers. The response will include at most this many groups but may include fewer. If this value is omitted, the response will return the default number of groups allowed by ListRoleMembers.
groups_skip	integer <uint32> >= 0 Default: 0 Number of groups to skip for ListRoleMembers. This is the zero-based index of the first group result.
identities_page_size	integer <uint32> >= 0 Number of identities returned per page for ListRoleMembers. The response will include at most this many identities but may include fewer. If this value is omitted, the response will return the default number of identities allowed by ListRoleMembers.
identities_skip	integer <uint32> >= 0 Default: 0 Number of identities to skip for ListRoleMembers. This is the zero-based index of the first identity result.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.

Responses

Response samples

Content type

application/json

{"groups": [{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"display_name": "Realm Administrators",
"description": "A group of realm administrators.",
"create_time": "2022-03-14T03:42:52.905Z",
"update_time": "2022-06-14T05:55:23.823Z"
}
],
"total_groups_size": 1,
"identities": [{"id": "e372db224c06e850",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"display_name": "Test Identity",
"create_time": "2022-04-12T05:53:07.119Z",
"update_time": "2022-06-16T14:31:03.770Z",
"traits": {"type": "traits_v0",
"username": "test",
"primary_email_address": "test@example.com"
}
}
],
"total_identities_size": 1
}

Assign Scopes to a Role

To assign scopes to a role, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:addScopes. The request must contain at least one and no more than 1000 scopes.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.
role_id required	string Example: fb785d40cbe4fc0d A unique identifier for a role.

Request Body schema: application/json

scopes

required

Array of strings [ 1 .. 1000 ] items

Scopes to be assigned to the role.

Responses

Request samples

Payload

Content type

application/json

{"scopes": ["identities:read"
]
}

Response samples

Content type

application/json

{"id": "fb785d40cbe4fc0d",
"resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
"realm_id": "bb26e0e8ecdef843",
"tenant_id": "00010036778ce59f",
"description": "Help Desk",
"display_name": "Customer support personnel.",
"create_time": "2023-02-14T18:18:58.332Z",
"update_time": "2023-02-14T18:18:58.332Z"
}

Unassign Scopes from a Role

To unassign scopes from a role, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:deleteScopes. The request must contain at least one and no more than 1000 scopes.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.
role_id required	string Example: fb785d40cbe4fc0d A unique identifier for a role.

Request Body schema: application/json

scopes

required

Array of strings [ 1 .. 1000 ] items

Scopes to be removed from the role.

Responses

Request samples

Payload

Content type

application/json

{"scopes": ["identities:read"
]
}

Response samples

Content type

application/json

{"id": "fb785d40cbe4fc0d",
"resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
"realm_id": "bb26e0e8ecdef843",
"tenant_id": "00010036778ce59f",
"description": "Help Desk",
"display_name": "Customer support personnel.",
"create_time": "2023-02-14T18:18:58.332Z",
"update_time": "2023-02-14T18:18:58.332Z"
}

List Scopes for a Role

To list scopes assigned to a role, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:listScopes.

The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of scopes in the response. Note that the maximum and default page sizes are subject to change.

When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.

Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
resource_server_id required	string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server.
role_id required	string Example: fb785d40cbe4fc0d A unique identifier for a role.

query Parameters

page_size	integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method.
page_token	string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified.
skip	integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

Content type

application/json

{"scopes": ["identities:read"
],
"total_size": 1
}

Tokens

List Tokens

To list all tokens issued by an application, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/applications/$APPLICATION_ID/tokens. The $APPLICATION_ID in path corresponds to the application that is the issuer of the token. To filter the list of tokens by a principal, set principal_type and principal_id. These parameters are optional. The response will contain at most 100 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 100 items. There is no defined ordering of the list of tokens in the response. Note that the maximum and default page sizes are subject to change. When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request. Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
application_id required	string Example: 38833c36-6f47-4992-9329-ea0a00915137 A unique identifier for an application.

query Parameters

principal_type	string Type of the principal. Allowable values are: `application` `identity`
principal_id	string A unique identifier for a principal. This might be an application ID or an identity ID depending on the type of principal.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"tokens": [{"id": "cTXMRjNrTz7w3p7wO5HJ5cUTpFt5Z3yL",
"display_name": "Testing token only for creating applications",
"scopes": ["applications:create"
],
"token_suffix": "JV_adQssw5c",
"token_format": "self_contained",
"expires": 1677246914,
"issued_at": 1677246914,
"token_type": "access"
}
],
"total_size": 1
}

Revoke a Token

To revoke a token, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/applications/$APPLICATION_ID/tokens/$TOKEN_ID. The $APPLICATION_ID in path corresponds to the application that is the issuer of the token. A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully. If the token ID is not available, the access token must be revoked via the RFC-7009 revoke endpoint.

Authorizations:

BearerAuth

path Parameters

tenant_id required	string Example: 000176d94fd7b4d1 A unique identifier for a tenant.
realm_id required	string Example: 19a95130480dfa79 A unique identifier for a realm.
application_id required	string Example: 38833c36-6f47-4992-9329-ea0a00915137 A unique identifier for an application.
token_id required	string A unique identifier for a token. For JWS tokens, this corresponds to the value of the `jti` token claim.

Responses

Response samples

401
403
404
500

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized"
}

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.

Authorizations:

BearerAuth

Request Body schema: application/json

required

object (User)

A user represents a human entity as defined by RFC 7643 Section 4.1. A user cooresponds to the identity resource in Beyond Identity.

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.
userName	string non-empty The unique username of the user.
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.
	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

Payload

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"active": true,
"userName": "bjensen",
"displayName": "Ms. Barbara Jensen",
"externalId": "bjensen",
"name": {"familyName": "Jensen",
"givenName": "Barbara"
},
"emails": [{"value": "bjensen@example.com",
"primary": true
}
]
}

Response samples

201
400
401
403
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "2819c223-7f76-453a-919d-413861904646",
"externalId": "bjensen",
"userName": "bjensen",
"displayName": "Ms. Barbara J Jensen III",
"name": [{"familyName": "Jensen"
},
{"givenName": "Barbara"
}
],
"active": true,
"emails": [{"primary": true,
"value": "bjensen@example.com"
}
],
"meta": {"resourceType": "User",
"created": "2022-10-12T05:11:47Z",
"lastModified": "2023-03-30T06:00:03Z",
"location": "Users/2819c223-7f76-453a-919d-413861904646",
"version": "W/0"
}
}

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 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> >= 1 Default: 1 The 1-based index of the first query result.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "2819c223-7f76-453a-919d-413861904646",
"externalId": "bjensen",
"userName": "bjensen",
"displayName": "Ms. Barbara J Jensen III",
"name": [{"familyName": "Jensen"
},
{"givenName": "Barbara"
}
],
"active": true,
"emails": [{"primary": true,
"value": "bjensen@example.com"
}
],
"meta": {"resourceType": "User",
"created": "2022-10-12T05:11:47Z",
"lastModified": "2023-03-30T06:00:03Z",
"location": "Users/2819c223-7f76-453a-919d-413861904646",
"version": "W/0"
}
}
],
"itemsPerPage": 1000,
"startIndex": 1,
"totalResults": 1
}

Retrieve an Existing User

To retrieve an existing user, send a GET request to /Users/$USER_ID.

Authorizations:

BearerAuth

path Parameters

user_id

required

string non-empty

ID of the user. This corresponds to the identity ID.

Responses

Response samples

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "ed9fcce6-ec82-458e-ae58-e2d975cfc32d",
"externalId": "external-id-abcdef",
"userName": "test_user",
"displayName": "Test User",
"active": true,
"emails": [{"primary": true,
"value": "test@test.com"
}
],
"name": {"givenName": "Barbara",
"familyName": "Jensen"
},
"meta": {"resourceType": "Group",
"created": "2022-04-07T07:23:33.000Z",
"lastModified": "2023-03-30T07:00:14.000Z",
"location": "Groups/ed9fcce6-ec82-458e-ae58-e2d975cfc32d",
"version": "W/0"
}
}

Patch a User

To update only specific attributes of an existing user, send a PATCH request to /Users/$USER_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.

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

Currently, only "add" and "replace" operations are supported for users.

Authorizations:

BearerAuth

path Parameters

user_id

required

string non-empty

ID of the user. This corresponds to the identity ID.

Request Body schema: application/json

required

object (User)

A user represents a human entity as defined by RFC 7643 Section 4.1. A user cooresponds to the identity resource in Beyond Identity.

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.
userName	string non-empty The unique username of the user.
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.
	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

Payload

Content type

application/json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [{"op": "replace",
"path": "displayName",
"value": "Ms. Barbara J Jensen III"
}
]
}

Response samples

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "2819c223-7f76-453a-919d-413861904646",
"externalId": "bjensen",
"userName": "bjensen",
"displayName": "Ms. Barbara J Jensen III",
"name": [{"familyName": "Jensen"
},
{"givenName": "Barbara"
}
],
"active": true,
"emails": [{"primary": true,
"value": "bjensen@example.com"
}
],
"meta": {"resourceType": "User",
"created": "2022-10-12T05:11:47Z",
"lastModified": "2023-03-30T06:00:03Z",
"location": "Users/2819c223-7f76-453a-919d-413861904646",
"version": "W/0"
}
}

Replace a User

To replace all attributes of an existing user, send a PUT request to /Users/$USER_ID. Values in the request body for immutable or read-only fields will be ignored.

Authorizations:

BearerAuth

path Parameters

user_id

required

string non-empty

ID of the user. This corresponds to the identity ID.

Request Body schema: application/json

required

object (User)

A user represents a human entity as defined by RFC 7643 Section 4.1. A user cooresponds to the identity resource in Beyond Identity.

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.
userName	string non-empty The unique username of the user.
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.
	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

Payload

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"active": true,
"userName": "bjensen",
"externalId": "bjensen",
"displayName": "Ms. Barbara J Jensen III",
"name": {"familyName": "Jensen",
"givenName": "Barbara"
},
"emails": [{"value": "bjensen@example.com",
"primary": true
}
]
}

Response samples

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "2819c223-7f76-453a-919d-413861904646",
"externalId": "bjensen",
"userName": "bjensen",
"displayName": "Ms. Barbara J Jensen III",
"name": [{"familyName": "Jensen"
},
{"givenName": "Barbara"
}
],
"active": true,
"emails": [{"primary": true,
"value": "bjensen@example.com"
}
],
"meta": {"resourceType": "User",
"created": "2022-10-12T05:11:47Z",
"lastModified": "2023-03-30T06:00:03Z",
"location": "Users/2819c223-7f76-453a-919d-413861904646",
"version": "W/0"
}
}

Delete a User

To delete a user, send a DELETE request to /Users/$USER_ID.

Authorizations:

BearerAuth

path Parameters

user_id

required

string non-empty

ID of the user. This corresponds to the identity ID.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"
],
"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

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

Authorizations:

BearerAuth

Request Body schema: application/json

required

object (Group)

A group is a collection of users corresponding to RFC 7643 Section 4.2.

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	string non-empty The unique display name of the group. This name is used for display purposes.
	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

Payload

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "22e7c78c-39ff-4501-8ed4-32d0479e54c1",
"displayName": "Test Group"
}

Response samples

201
400
401
403
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "22e7c78c-39ff-4501-8ed4-32d0479e54c1",
"displayName": "Test Group",
"meta": {"created": "2023-04-10T06:08:28Z",
"lastModified": "2023-04-10T06:08:28Z",
"location": "Groups/22e7c78c-39ff-4501-8ed4-32d0479e54c1",
"resourceType": "Group",
"version": "W/0"
}
}

List All Groups

To list all groups, send a GET request to /Groups.

Currently, filtering on groups only supports the eq and ne operators and the displayName attribute.

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 groups in the response. Note that the maximum page size is subject to change.

Members will not be returned with the group.

Authorizations:

BearerAuth

query Parameters

filter	string 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> >= 1 Default: 1 The 1-based index of the first query result.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "22e7c78c-39ff-4501-8ed4-32d0479e54c1",
"displayName": "Test Group",
"meta": {"created": "2023-04-10T06:08:28Z",
"lastModified": "2023-04-10T06:08:28Z",
"location": "Groups/22e7c78c-39ff-4501-8ed4-32d0479e54c1",
"resourceType": "Group",
"version": "W/0"
}
}
],
"itemsPerPage": 1000,
"startIndex": 1,
"totalResults": 1
}

Retrieve an existing group

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

Authorizations:

BearerAuth

path Parameters

group_id

required

string non-empty

ID of the group.

Responses

Response samples

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "ed9fcce6-ec82-458e-ae58-e2d975cfc32d",
"displayName": "Help Desk",
"meta": {"resourceType": "Group",
"created": "2022-04-07T07:23:33.000Z",
"lastModified": "2023-03-30T07:00:14.000Z",
"location": "Groups/ed9fcce6-ec82-458e-ae58-e2d975cfc32d",
"version": "W/0"
}
}

Patch a Group

To update only specific attributes of an existing group, send a PATCH request to /Groups/$GROUP_ID. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.

Note that 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 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.

Currently, "replace" operations are supported for displayName while "add" and "remove" operations are supported for members. Multiple members may be added at a time, but batch remove is not supported. Note that while member changes will take affect, they will not be reflected in the response as members are not currently returned with groups.

Authorizations:

BearerAuth

path Parameters

group_id

required

string non-empty

ID of the group.

Request Body schema: application/json

required

object (Group)

A group is a collection of users corresponding to RFC 7643 Section 4.2.

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	string non-empty The unique display name of the group. This name is used for display purposes.
	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

Payload

Content type

application/json

Example

Replace DisplayName

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

Response samples

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "22e7c78c-39ff-4501-8ed4-32d0479e54c1",
"displayName": "Test Group",
"meta": {"created": "2023-04-10T06:08:28Z",
"lastModified": "2023-04-10T06:08:28Z",
"location": "Groups/22e7c78c-39ff-4501-8ed4-32d0479e54c1",
"resourceType": "Group",
"version": "W/0"
}
}

Delete a Group

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

Authorizations:

BearerAuth

path Parameters

group_id

required

string non-empty

ID of the group.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"
],
"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

200
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"
],
"id": "User",
"name": "User",
"description": "User Account",
"endpoint": "/Users",
"schema": "urn:ietf:params:scim:schemas:core:2.0:User",
"schemaExtensions": [ ]
},
{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"
],
"id": "Group",
"name": "Group",
"description": "User Groups",
"endpoint": "/Groups",
"schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
"schemaExtensions": [{"required": false,
"schema": "urn:scim:schemas:extension:byndid:1.0:Group"
}
]
}
],
"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

200
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [{"id": "urn:ietf:params:scim:schemas:core:2.0:User",
"name": "User",
"description": "User resource",
"attributes": [{"name": "externalId",
"type": "string",
"description": "A String that is an identifier for the resource as defined by the provisioning client.\n",
"caseExact": true,
"multiValued": false,
"mutability": "readWrite",
"required": true,
"returned": "always",
"uniqueness": "server"
},
{"name": "userName",
"type": "string",
"caseExact": true,
"description": "The username of the user. The value of this field will be returned as the subject of a OIDC ID Token.\n",
"multiValued": false,
"mutability": "readWrite",
"required": true,
"returned": "always",
"uniqueness": "server"
},
{"name": "displayName",
"type": "string",
"caseExact": true,
"description": "The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known.\n",
"multiValued": false,
"mutability": "readWrite",
"required": true,
"returned": "always",
"uniqueness": "none"
},
{"name": "active",
"type": "boolean",
"description": "A Boolean value indicating the User's administrative status within the Beyond Identity Service.\n",
"multiValued": false,
"mutability": "readWrite",
"required": true,
"returned": "always"
},
{"name": "name",
"type": "complex",
"description": "The components of the user's real name.",
"multiValued": false,
"mutability": "readWrite",
"required": false,
"returned": "request",
"subAttributes": [{"name": "familyName",
"type": "string",
"description": "The family name of the User, or last name in most Western languages (e.g., 'Jensen' given the full name 'Ms. Barbara J Jensen, III').\n",
"caseExact": true,
"multiValued": false,
"mutability": "readWrite",
"required": true,
"returned": "request",
"uniqueness": "none"
},
{"name": "givenName",
"type": "string",
"description": "The given name of the User, or first name in most Western languages (e.g., \"Barbara\" given the full name \"Ms. Barbara Jane Jensen, III\").\n",
"caseExact": true,
"multiValued": false,
"mutability": "readWrite",
"required": true,
"returned": "request",
"uniqueness": "none"
}
]
},
{"name": "emails",
"type": "complex",
"description": "Email addresses for the User. Providing a primary is required.\n",
"multiValued": true,
"mutability": "readWrite",
"required": true,
"returned": "always",
"subAttributes": [{"name": "value",
"type": "string",
"description": "",
"caseExact": false,
"multiValued": false,
"mutability": "readWrite",
"required": false,
"returned": "default",
"uniqueness": "none"
},
{"name": "primary",
"type": "boolean",
"description": "",
"multiValued": false,
"mutability": "readWrite",
"required": false,
"returned": "default"
}
]
}
]
},
{"id": "urn:ietf:params:scim:schemas:core:2.0:Group",
"name": "Group",
"description": "Group resource",
"attributes": [{"name": "id",
"type": "string",
"description": "group id",
"caseExact": false,
"multiValued": false,
"mutability": "readWrite",
"required": false,
"returned": "default",
"uniqueness": "server"
},
{"name": "displayName",
"type": "string",
"description": "A human-readable name for the Group.",
"caseExact": false,
"multiValued": false,
"mutability": "readWrite",
"required": false,
"returned": "default",
"uniqueness": "server"
},
{"name": "members",
"type": "complex",
"description": "A list of members of the group.",
"multiValued": true,
"mutability": "readWrite",
"required": false,
"returned": "default",
"subAttributes": [{"name": "value",
"type": "string",
"description": "Identifier of the member of this Group.",
"caseExact": false,
"multiValued": false,
"mutability": "immutable",
"required": false,
"returned": "default",
"uniqueness": "none"
},
{"name": "",
"type": "reference",
"description": "The URI corresponding to a SCIM resource that is a member of this Group.\n",
"caseExact": true,
"multiValued": false,
"mutability": "immutable",
"referenceTypes": ["User"
],
"required": false,
"returned": "default",
"uniqueness": "none"
},
{"name": "type",
"type": "string",
"description": "A label indicating the type of resource",
"canonicalValues": ["User",
"Group"
],
"caseExact": false,
"multiValued": false,
"mutability": "immutable",
"required": false,
"returned": "default",
"uniqueness": "none"
}
]
}
]
}
],
"itemsPerPage": 1000,
"startIndex": 1,
"totalResults": 2
}

Retrieve the Service Provider Configuration

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

Authorizations:

BearerAuth

Responses

Response samples

200
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
],
"authenticationSchemes": [{"name": "",
"description": "",
"documentationUri": "",
"primary": false,
"specUri": "",
"type": "oauthbearertoken"
}
],
"bulk": {"maxOperations": 1000,
"maxPayloadSize": 1048576,
"supported": false
},
"changePassword": {"supported": false
},
"documentationUri": "",
"etag": {"supported": false
},
"filter": {"maxResults": 1000,
"supported": true
},
"patch": {"supported": true
},
"sort": {"supported": false
}
}