Skip to main content
Documentation Powered by Redocly

Beyond Identity API (1.0.1)

Download OpenAPI specification:Download

E-mail: support@beyondidentity.com

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 through OAuth 2.0 or OIDC. 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

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

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 All 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

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 or groups. 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

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

description
string

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 All 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

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

description
string

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

List All 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
}

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

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

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

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 All Identities for a Realm

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

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 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
{
  • "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

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

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. The identity must must first be removed from all groups 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 All 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
}

Credentials

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

List All 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.

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 is automatically set on creation. This field is immutable.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{}

List All 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",
  • "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

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.

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

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

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

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.

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 All 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

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

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

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.

Web Authenticator (object) or Embedded SDK Authenticator (object)

An object specifying the settings for the supported authenticator type.

One of
type
required
string
Value: "hosted_web"

Responses

Request samples

Content type
application/json
{}

Response samples

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

List All 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

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",
  • "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

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.

Web Authenticator (object) or Embedded SDK Authenticator (object)

An object specifying the settings for the supported authenticator type.

One of
type
required
string
Value: "hosted_web"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
  • "realm_id": "caf2ff640497591a",
  • "tenant_id": "00011f1183c67b69",
  • "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

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 All 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

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.

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

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

A unique identifier for a resource server.

Responses

Response samples

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