Skip to main content

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

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

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

Response samples

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

Content type
application/json
{
  • "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"
}

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

Content type
application/json
{
  • "realms": [
    ],
  • "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

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

Content type
application/json
{
  • "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

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

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

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": [
    ],
  • "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

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

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

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

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

Content type
application/json
{
  • "identity_ids": [
    ]
}

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

Content type
application/json
{
  • "identity_ids": [
    ]
}

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": [
    ],
  • "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": [
    ],
  • "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

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

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": {
    }
}

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": [
    ],
  • "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

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": {
    }
}

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

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

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": {
    }
}

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

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": [
    ],
  • "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": [
    ],
  • "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

Content type
application/json
{
  • "credentials": [
    ],
  • "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

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

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

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

Response samples

Content type
application/json
Example
{}

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

Content type
application/json
{
  • "credential_binding_jobs": [
    ],
  • "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

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

Content type
application/json
{}

Response samples

Content type
application/json
{}

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

Content type
application/json
{}

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

Content type
application/json
{}

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

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

Response samples

Content type
application/json
{}

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

Content type
application/json
{
  • "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": {
    }
}

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": [
    ],
  • "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

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": {
    }
}

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

Content type
application/json
{
  • "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": {
    }
}

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

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

Content type
application/json
{}

Response samples

Content type
application/json
Example
{
  • "id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
  • "realm_id": "caf2ff640497591a",
  • "tenant_id": "00011f1183c67b69",
  • "display_name": "Pet Authenticator Configuration",
  • "config": {
    }
}

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": [
    ],
  • "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

Content type
application/json
{
  • "id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
  • "realm_id": "caf2ff640497591a",
  • "tenant_id": "00011f1183c67b69",
  • "display_name": "Pet Authenticator Configuration",
  • "config": {
    }
}

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

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

Response samples

Content type
application/json
Example
{
  • "id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
  • "realm_id": "caf2ff640497591a",
  • "tenant_id": "00011f1183c67b69",
  • "display_name": "Pet Authenticator Configuration",
  • "config": {
    }
}

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

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

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

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": [
    ]
}

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": [
    ],
  • "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

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": [
    ]
}

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

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

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": [
    ]
}

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

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

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

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": [
    ],
  • "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

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

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

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

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

Content type
application/json
{
  • "group_ids": [
    ],
  • "identity_ids": [
    ]
}

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

Content type
application/json
{
  • "group_ids": [
    ],
  • "identity_ids": [
    ]
}

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": [
    ],
  • "total_groups_size": 1,
  • "identities": [
    ],
  • "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

Content type
application/json
{
  • "scopes": [
    ]
}

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

Content type
application/json
{
  • "scopes": [
    ]
}

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": [
    ],
  • "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

Content type
application/json
{
  • "tokens": [
    ],
  • "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

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