Beyond Identity Secure Access API (1.7.0)

Download OpenAPI specification:Download

Introduction

NOTE: To determine if you are accessing the Secure Access Platform, check the URL of your Admin Console. If it looks like one of the following, you are using the Secure Access Platform:

https://console.beyondidentity.com (Localized to your region)
https://console-us.beyondidentity.com (US region)
https://console-eu.beyondidentity.com (EU region)
https://console.us1.beyondidentity-gov.com (US FedRAMP)

If your Admin Console URL does not look like one of the above, you are using the Secure Workforce Platform. Please refer to the Secure Workforce API documentation.

The Beyond Identity Secure Access API defines methods for managing resources in the Beyond Identity Secure Access platform.

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.

Base API URLs

The base API URLs is determined by the region your tenant is hosted in OR if you are a FedRAMP customer.

US Region

If you are a US region customer, your base API URLs will be:

https://api-us.beyondidentity.com
https://auth-us.beyondidentity.com

EU Region

If you are a EU region customer, your base API URLs will be:

https://api-eu.beyondidentity.com
https://auth-eu.beyondidentity.com

US FedRAMP

NOTE: The FedRAMP version of Secure Access is released approximately two weeks after the commercial version, so some API endpoints may not be available immediately.

If you are a FedRAMP customer in the US region, your base API URLs will be:

https://api.us1.beyondidentity-gov.com
https://auth.us1.beyondidentity-gov.com

For all the examples in this document, we will use the US region API base URL. You can always replace https://api-us.beyondidentity.com and https://auth-us.beyondidentity.com in the examples to use the proper base URL for your tenant.

Authentication

All Beyond Identity API endpoints require authentication using an access token. The access token is generated through OAuth 2.0 or OIDC, using the authorization code flow or the client credentials flow.

The simplest way to acquire an access token is through the Beyond Identity Admin Console. Under the "Applications" tab, select the "Beyond Identity Management API" application, navigate to the "API Tokens" tab, and then click on "Create token".

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

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

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

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

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

Requests and Responses

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

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

Resource fields may be described as read-only and immutable. A read-only field is only provided on the response. An immutable field is only assigned once and may not be changed after. For example, system-generated IDs are described as both read-only and immutable.

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

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

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

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

Example Response for a Realm

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

Example Response for a Collection of Realms

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

HTTP Statuses

The API returns standard HTTP statuses and error codes.

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

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

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

All error responses include a JSON object with a code field and a message field. code contains a human-readable name for the HTTP status code and message contains a high-level description of the error. The error object may also contain additional error details which may be used by the client to determine the exact cause of the error. Refer to each API method's examples to determine the specific error detail types supported for that method.

Invalid Access Token Example

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

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

Permission Denied Example

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

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

Missing Resource Example

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

HTTP/1.1 404 Not Found
{
  "code": "not_found",
  "message": "group not found"
  "details": [
    {
      "type": "ResourceInfo",
      "resource_type": "Group",
      "id": "4822738be6b7f658",
      "description": "group not found"
    }
  ],
}

Invalid Parameters Example

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

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

Tenants

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

Retrieve an Existing Tenant

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

Authorizations:

BearerAuth

path Parameters

tenant_id

required

string

Example: 000176d94fd7b4d1

A unique identifier for a tenant.

Responses

Response samples

200
401
403
500

Content type

application/json

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

Patch a Tenant

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

Authorizations:

BearerAuth

path Parameters

tenant_id

required

string

Example: 000176d94fd7b4d1

A unique identifier for a tenant.

Request Body schema: application/json

Updates to the specified tenant.

required

object (Tenant)

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

display_name

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400
401
403
500

Content type

application/json

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

Realms

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

Create a New Realm

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

Authorizations:

BearerAuth

path Parameters

tenant_id

required

string

Example: 000176d94fd7b4d1

A unique identifier for a tenant.

Request Body schema: application/json

required

object (Realm)

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

display_name	string [ 1 .. 64 ] characters ^[^{}[\]<>;:?\\/\|^%$#=~`!]$ A human-readable name for the realm. This name is used for display purposes.
classification	string Classification of the realm. Can be either SECURE_WORFORCE or SECURE_CUSTOMER

Responses

Request samples

Payload

Content type

application/json

{"realm": {"display_name": "Test Realm",
"classification": "SECURE_CUSTOMER"
}
}

Response samples

200
400
401
403
500

Content type

application/json

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

List Realms for a Tenant

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

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

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

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

Authorizations:

BearerAuth

path Parameters

tenant_id

required

string

Example: 000176d94fd7b4d1

A unique identifier for a tenant.

query Parameters

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

Responses

Response samples

200
400
401
403
500

Content type

application/json

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

Retrieve an Existing Realm

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

Authorizations:

BearerAuth

path Parameters

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

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "19a95130480dfa79",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Realm",
"classification": "SECURE_WORKFORCE",
"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.
classification	string Classification of the realm. Can be either SECURE_WORFORCE or SECURE_CUSTOMER

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Delete a Realm

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

Authorizations:

BearerAuth

path Parameters

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

Responses

Response samples

401
403
404
409
500

Content type

application/json

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

Groups

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

Create a New Group

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

required

object (Group)

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

List Groups for a Realm

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

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

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

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

Authorizations:

BearerAuth

path Parameters

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

query Parameters

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

Responses

Response samples

Content type

application/json

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

Retrieve an Existing Group

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

Authorizations:

BearerAuth

path Parameters

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

Responses

Response samples

200
401
403
404
500

Content type

application/json

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

Patch a Group

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

required

object (Group)

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Delete a Group

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

Authorizations:

BearerAuth

path Parameters

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

Responses

Response samples

401
403
404
409
500

Content type

application/json

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

Add Members to a Group

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

identity_ids

required

Array of strings [ 1 .. 1000 ] items

IDs of the identities to be added to the group.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Delete Members from a Group

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

identity_ids

required

Array of strings [ 1 .. 1000 ] items

IDs of the identities to be removed from the group.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

List Members for a Group

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

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

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

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

Authorizations:

BearerAuth

path Parameters

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

query Parameters

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

Responses

Response samples

Content type

application/json

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

List Role Memberships for a Group

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

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

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

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

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

Authorizations:

BearerAuth

path Parameters

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

query Parameters

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

Responses

Response samples

Content type

application/json

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

Identities

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

Create a New Identity

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

required

object (Identity)

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

List Identities for a Realm

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

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

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

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

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

Authorizations:

BearerAuth

path Parameters

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

query Parameters

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

Responses

Response samples

Content type

application/json

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

Batch delete identities.

To delete multiple identities in a realm, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities:batchDelete. The request must contain at least one and no more than 1000 identity IDs. If there are any repeating identity IDs, the request will fail. If there are any invalid identity IDs, the request will fail and no identities will be deleted. 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.

Request Body schema: application/json

ids

required

Array of strings [ 1 .. 1000 ] items

IDs of the identities to be deleted.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

401
403
404
500

Content type

application/json

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

Retrieve an Existing Identity

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

Authorizations:

BearerAuth

path Parameters

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

Responses

Response samples

200
401
403
404
500

Content type

application/json

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

Patch an Identity

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

required

object (Identity)

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Delete an Identity

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

Authorizations:

BearerAuth

path Parameters

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

Responses

Response samples

401
403
404
500

Content type

application/json

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

List Group Memberships for an Identity

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

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

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

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

Authorizations:

BearerAuth

path Parameters

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

query Parameters

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}:listGroups

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}:listGroups

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}:listGroups

Response samples

Content type

application/json

{"groups": [{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"display_name": "Realm Administrators",
"description": "A group of realm administrators.",
"create_time": "2022-03-14T03:42:52.905657Z",
"update_time": "2022-06-14T05:55:23.823187Z"
}
],
"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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}:listRoles

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}:listRoles

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}:listRoles

Response samples

Content type

application/json

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credentials

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credentials

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credentials

Response samples

200
400
401
403
500

Content type

application/json

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credentials/{credential_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credentials/{credential_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credentials/{credential_id}

Response samples

200
401
403
404
500

Content type

application/json

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

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credentials/{credential_id}:revoke

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credentials/{credential_id}:revoke

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credentials/{credential_id}:revoke

Response samples

200
401
403
404
500

Content type

application/json

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

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.
	object Representation of an authenticator configuration. This prescribes how an identity may authenticate themselves with Beyond Identity.
authenticator_config_id	string The ID of the authenticator configuration to be used to build the credential binding job. This field is immutable.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

Example

Delivery Method Return

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

List Credential Binding Jobs for an Identity

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

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

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

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

Authorizations:

BearerAuth

path Parameters

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

query Parameters

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs

Response samples

200
400
401
403
500

Content type

application/json

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

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. Supported filters attributes: state: the state of the credential binding job. delivery_method: the delivery method used for the credential binding job.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs/{credential_binding_job_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs/{credential_binding_job_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs/{credential_binding_job_id}

Response samples

200
401
403
404
500

Content type

application/json

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

Revocation of an active credential binding job.

To revoke an active credential binding job, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credential-binding-jobs/$CREDENTIAL_BINDING_JOB_ID:revoke. This endpoint invalidates a pending credential binding job, preventing a credential from being enrolled for the associated identity. If the specified job has already been completed, the revocation attempt will fail.

Authorizations:

None

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.

Request Body schema: application/json

object (Bind Credential Request)

Request for SetCredentialBindingJobRevoked. This request body is empty.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs/{credential_binding_job_id}:revoke

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs/{credential_binding_job_id}:revoke

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credential-binding-jobs/{credential_binding_job_id}:revoke

Request samples

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

{"id": "86b4f51481f09321",
"identity_id": "3d227b0d5949969d",
"realm_id": "9602e246c2ead9b2",
"tenant_id": "ce5ace5fc7e14d6a",
"credential_id": "9802966246819b35",
"batch_id": "9802966246819b35",
"delivery_method": "RETURN",
"state": "COMPLETE",
"post_binding_redirect_uri": "http://example.com/callback",
"authenticator_config": {"config": {"invocation_type": "automatic",
"invoke_url": "http://localhost:8092",
"trusted_origins": ["http://localhost:8092"
],
"type": "embedded",
"authentication_methods": [{"type": "email_one_time_password"
}
]
}
},
"authenticator_config_id": "76e9eab521a8b734",
"expire_time": "2022-05-12T20:29:47.636497Z",
"create_time": "2022-05-12T20:29:47.636497Z",
"update_time": "2022-05-12T20:29:47.636497Z"
}

Create a New Batch Credential Binding Job

To create a new batch credential binding job, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/batch-credential-binding-jobs. Values in the request body for read-only fields will be ignored. A maximum of 1000 credential binding jobs can be created in a single batch. Each realm can have up to 1000 credential binding jobs in the batch queue at any given time.

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

Batch credential binding job to be created.

required

object (BatchCredentialBindingJob)

A batch credential binding job manages the binding of credentials for multiple identities in a batch operation.

identity_ids required	Array of strings [ 1 .. 1000 ] items [ items non-empty ] The list of identities associated with the batch credential binding job.
required	object (BatchCredentialBindingJobTemplate) A batch credential binding job template provides a template for the credential binding jobs created via a batch.

Responses

Request samples

Payload

Content type

application/json

{"batch_credential_binding_job": {"identity_ids": ["3d227b0d5949969d",
"a3f28b7c9e6d1234",
"5c90d2af18e47b0e"
],
"job_template": {"authenticator_config_id": "67bb0acf12e5c899",
"post_binding_redirect_uri": "http://example.com/callback"
}
}
}

Response samples

200
401
403
429
500

Content type

application/json

{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"identity_ids": ["3d227b0d5949969d",
"a3f28b7c9e6d1234",
"5c90d2af18e47b0e"
],
"state": "RUNNING",
"state_commentary": {"errors": {"a3f28b7c9e6d1234": {"last_error": "Identity missing email address",
"failed_permanently": false
}
}
},
"job_template": {"authenticator_config_id": "67bb0acf12e5c899",
"post_binding_redirect_uri": "http://example.com/callback"
},
"create_time": "2022-03-14T03:42:52.905657Z",
"update_time": "2022-03-15T05:55:23.823187Z"
}

Retrieve an Existing Batch Credential Binding Job

To retrieve an existing batch credential binding job, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credential-binding-jobs/batch/$BATCH_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.
batch_credential_binding_job_id required	string Example: c15e004f-a7bc-459b-b035-cec40e07f537 A unique identifier for a batch credential binding job.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/batch-credential-binding-jobs/{batch_credential_binding_job_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/batch-credential-binding-jobs/{batch_credential_binding_job_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/batch-credential-binding-jobs/{batch_credential_binding_job_id}

Response samples

200
401
403
404
500

Content type

application/json

{"id": "81490afab171aef0",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"identity_ids": ["3d227b0d5949969d",
"a3f28b7c9e6d1234",
"5c90d2af18e47b0e"
],
"state": "RUNNING",
"state_commentary": {"errors": {"a3f28b7c9e6d1234": {"last_error": "Identity missing email address",
"failed_permanently": false
}
}
},
"job_template": {"authenticator_config_id": "67bb0acf12e5c899",
"post_binding_redirect_uri": "http://example.com/callback"
},
"create_time": "2022-03-14T03:42:52.905657Z",
"update_time": "2022-03-15T05:55:23.823187Z"
}

List Results of a Batch Credential Binding Job

To list the results of a batch credential binding job, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/batch-credential-binding-jobs/$BATCH_CREDENTIAL_BINDING_JOB_ID:listResults.

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.
batch_credential_binding_job_id required	string Example: c15e004f-a7bc-459b-b035-cec40e07f537 A unique identifier for a batch credential binding job.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/batch-credential-binding-jobs/{batch_credential_binding_job_id}:listResults

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/batch-credential-binding-jobs/{batch_credential_binding_job_id}:listResults

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/batch-credential-binding-jobs/{batch_credential_binding_job_id}:listResults

Response samples

200
401
403
404
500

Content type

application/json

{"job_results": [{"id": "81490afab171aef0",
"identity_id": "a3f28b7c9e6d1234",
"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.905657Z",
"create_time": "2022-03-14T03:42:52.905657Z",
"update_time": "2022-03-15T05:55:23.823187Z"
},
{"id": "81490afab171aef0",
"identity_id": "5c90d2af18e47b0e",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"delivery_method": "EMAIL",
"state": "LINK_OPENED",
"post_binding_redirect_uri": "http://example.com/callback",
"authenticator_config_id": "67bb0acf12e5c899",
"expire_time": "2022-03-21T03:42:52.905657Z",
"create_time": "2022-03-14T03:42:52.905657Z",
"update_time": "2022-03-15T05:55:23.823187Z"
},
{"id": "81490afab171aef0",
"identity_id": "e85de356dc78843a",
"realm_id": "7df92e4a38ba0993",
"tenant_id": "0001b42d80372976",
"delivery_method": "EMAIL",
"state": "REVOKED",
"post_binding_redirect_uri": "http://example.com/callback",
"authenticator_config_id": "67bb0acf12e5c899",
"expire_time": "2022-03-21T03:42:52.905657Z",
"create_time": "2022-03-14T03:42:52.905657Z",
"update_time": "2022-03-15T05:55:23.823187Z"
}
],
"total_success_count": 1,
"total_failure_count": 1,
"total_pending_count": 1,
"total_size": 3
}

Themes

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

Create a New Theme

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

Theme to be created.

object (Theme)

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Get the Active Theme

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

Authorizations:

BearerAuth

path Parameters

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

Responses

Response samples

200
401
403
404
500

Content type

application/json

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

Retrive an Existing Theme

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

Authorizations:

BearerAuth

path Parameters

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

Responses

Response samples

200
401
403
404
500

Content type

application/json

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

Patch a Theme

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

Theme to be updated.

object (Theme)

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Applications

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

Create a New Application

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

required

object (Application)

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

List Applications for a Realm

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

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

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

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

Authorizations:

BearerAuth

path Parameters

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

query Parameters

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

Responses

Response samples

Content type

application/json

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

Retrieve an Existing Application

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

Authorizations:

BearerAuth

path Parameters

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

Responses

Response samples

200
401
403
404
500

Content type

application/json

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

Patch an Application

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

required

object (Application)

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Delete an Application

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

Authorizations:

BearerAuth

path Parameters

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

Responses

Response samples

401
403
404
500

Content type

application/json

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

Authenticator Configurations

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

Create a New Authenticator Configuration

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

required

object (Authenticator Configuration)

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

Example

Success Embedded

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

List Authenticator Configurations for a Realm

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

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

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

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

Authorizations:

BearerAuth

path Parameters

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

query Parameters

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

Responses

Response samples

Content type

application/json

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

Retrieve an Existing Authenticator Configuration

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

Authorizations:

BearerAuth

path Parameters

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs/{authenticator_config_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs/{authenticator_config_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs/{authenticator_config_id}

Response samples

200
401
403
404
500

Content type

application/json

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

Patch an Authenticator Configuration

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

required

object (Authenticator Configuration)

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

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs/{authenticator_config_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs/{authenticator_config_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs/{authenticator_config_id}

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

Example

Success Embedded

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

Delete an Authenticator Configuration

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

Authorizations:

BearerAuth

path Parameters

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs/{authenticator_config_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs/{authenticator_config_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs/{authenticator_config_id}

Response samples

401
403
404
500

Content type

application/json

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

Identity Provider

Identity providers enable integration with external systems to support IdP-authorized workflows, such as passkey enrollment. They serve as the counterpart to SSO applications, focusing on initiating authentication workflows and enabling secure interactions.

Lists Identity Providers by Realm.

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.
sso_config_id required	string A unique identifier of the sso configuration

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.

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"identity_providers": [{"id": "string",
"tenant_id": "0001f1f460b1ace6",
"realm_id": "8f5bec58229e6f29",
"display_name": "string",
"protocol_config": {"type": "oidc_idp",
"client_id": "string",
"client_secret": "string",
"token_scopes": ["string"
],
"identity_attribute": "id",
"pkce": "s256",
"jwks_url": "string",
"token_url": "string",
"authorize_url": "string",
"redirect_url": "string",
"identifying_claim_name": "string"
}
}
],
"total_size": 0,
"next_page_token": "string"
}

Creates a new identity provider.

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.

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Request Body schema: application/json

display_name required	string The human-readable name associated with the identity provider.
required	IdentityProviderProtocolConfigOidcIdp (object) The kind of protocol we should use to communicate with the identity provider.

Responses

Request samples

Payload

Content type

application/json

{"display_name": "string",
"protocol_config": {"type": "oidc_idp",
"client_id": "string",
"client_secret": "string",
"token_scopes": ["string"
],
"identity_attribute": "id",
"pkce": "s256",
"jwks_url": "string",
"token_url": "string",
"authorize_url": "string",
"identifying_claim_name": "string"
}
}

Response samples

200
400
401
403
500

Content type

application/json

{"type": "oidc_idp",
"client_id": "string",
"client_secret": "string",
"token_scopes": ["string"
],
"identity_attribute": "id",
"pkce": "s256",
"jwks_url": "string",
"token_url": "string",
"authorize_url": "string",
"redirect_url": "string",
"identifying_claim_name": "string"
}

Updates an identity provider.

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_provider_id required	string Example: e372db224c06e850 A unique identifier for an identity provider.

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Request Body schema: application/json

object

The identity provider object.

display_name	string The human-readable name associated with the identity provider.
	any The kind of protocol we should use to communicate with the identity provider.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers/{identity_provider_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers/{identity_provider_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers/{identity_provider_id}

Request samples

Payload

Content type

application/json

{"identity_provider": {"display_name": "string",
"protocol_config": {"type": "oidc_idp",
"client_id": "string",
"client_secret": "string",
"token_scopes": ["string"
],
"identity_attribute": "id",
"pkce": "s256",
"jwks_url": "string",
"token_url": "string",
"authorize_url": "string",
"identifying_claim_name": "string"
}
}
}

Response samples

200
400
401
403
500

Content type

application/json

{"id": "string",
"tenant_id": "0001f1f460b1ace6",
"realm_id": "8f5bec58229e6f29",
"display_name": "string",
"protocol_config": {"type": "oidc_idp",
"client_id": "string",
"client_secret": "string",
"token_scopes": ["string"
],
"identity_attribute": "id",
"pkce": "s256",
"jwks_url": "string",
"token_url": "string",
"authorize_url": "string",
"redirect_url": "string",
"identifying_claim_name": "string"
}
}

Retrieves data about an Identity Provider.

Retrieves data about an identity provider.

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_provider_id required	string Example: e372db224c06e850 A unique identifier for an identity provider.

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers/{identity_provider_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers/{identity_provider_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers/{identity_provider_id}

Response samples

200
400
401
403
500

Content type

application/json

{"id": "string",
"tenant_id": "0001f1f460b1ace6",
"realm_id": "8f5bec58229e6f29",
"display_name": "string",
"protocol_config": {"type": "oidc_idp",
"client_id": "string",
"client_secret": "string",
"token_scopes": ["string"
],
"identity_attribute": "id",
"pkce": "s256",
"jwks_url": "string",
"token_url": "string",
"authorize_url": "string",
"redirect_url": "string",
"identifying_claim_name": "string"
}
}

Deletes an Identity Provider.

Deletes an identity provider.

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_provider_id required	string Example: e372db224c06e850 A unique identifier for an identity provider.

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers/{identity_provider_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers/{identity_provider_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identity-providers/{identity_provider_id}

Response samples

400
401
403
500

Content type

application/json

{"code": "string",
"message": "string",
"details": [{"type": "string"
}
]
}

SSO Configs

An SSO configuration defines how end users interact with supported SSO protocols and related services. Each configuration type represents a protocol or integration (e.g., SAML, WS-Federation, OIDC, SCIM) supported by Beyond Identity. An SSO configuration provides a flexible framework for managing authentication, provisioning, and other integrations. It abstracts application protocols, inbound and outbound provisioning, and supports named integrations. Additionally, it includes features like user or group assignments, visual tiles in the SSO interface, and compatibility with multiple authentication and provisioning standards. This makes SSO configurations versatile for both authentication and non-authentication use cases.

Create a new SSO Config.

To create a new SSO Config, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/sso-configs.

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.

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Request Body schema: application/json

required

object (SsoConfig)

Represents an SSO config as a request body.

is_migrated	boolean Indicates that the SSO Config was added by a script such as fast migrate
display_name required	string A human-readable name for the application. This name is used for display purposes.
required	SsoConfigBookmark (object) or SsoConfigEntraIdExternalAuthMethod (object) or SsoConfigGenericOidc (object) or SsoConfigOidcIdp (object) or object or object or SsoConfigOktaBiIdp (object) or SsoConfigRealityCheck (object) or SsoConfigWsFed (object) (SsoConfigPayload)

Responses

Request samples

Payload

Content type

application/json

{"sso_config": {"is_migrated": true,
"display_name": "string",
"payload": {"type": "bookmark",
"login_link": "string",
"icon": "string",
"is_tile_visible": true
}
}
}

Response samples

200
400
401
403
500

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"display_name": "string",
"payload": {"type": "bookmark",
"login_link": "string",
"icon": "string",
"is_tile_visible": true,
"application_tile_id": "string"
}
}

List SSO Configs for a Realm.

To list SSO Configs for a Realm, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/sso-configs.

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.

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.
type	Array of strings (SsoConfigType) Items Enum: "bookmark" "entra_id_external_auth_methods" "generic_oidc" "generic_oidc_idp" "generic_saml" "okta_idp" "okta_sso_bi_idp" "scim" "ws_fed" The type of sso config to filter by. You may query with multiple types for example "/sso-configs?type=generic_oidc&type=generic_oid_idp"
is_migrated	boolean
order_by	string

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"sso_configs": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"display_name": "string",
"payload": {"type": "bookmark",
"login_link": "string",
"icon": "string",
"is_tile_visible": true
}
}
],
"total_size": 0,
"next_page_token": "string"
}

Retrieves an existing SSO Config.

To retrieve an existing SSO Config, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/sso-configs/$SSO_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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"display_name": "string",
"payload": {"type": "bookmark",
"login_link": "string",
"icon": "string",
"is_tile_visible": true,
"application_tile_id": "string"
}
}

Updates an SSO Config by its 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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Request Body schema: application/json
required

required

SsoConfigBookmarkPartialUpdate (object) or SsoConfigEntraIdAuthMethodPartial (object) or SsoConfigGenericOidcPartialUpdate (object) or SsoConfigGenericOidcIdpPartialUpdate (object) or SsoConfigSamlPartialUpdate (object) or object or SsoConfigOktaBiIdpPartialUpdate (object) or SsoConfigRealityCheckPartialUpdate (object) or SsoConfigWsFedPartialUpdate (object) (SsoConfigPartialUpdatePayload)

One of

type required	string (SsoConfigType) Enum: "bookmark" "entra_id_external_auth_methods" "generic_oidc" "generic_oidc_idp" "generic_saml" "okta_idp" "okta_sso_bi_idp" "scim" "ws_fed" Describes the type of sso config.
login_link	string
icon	string
is_tile_visible	boolean

Responses

Request samples

Payload

Content type

application/json

{"sso_config": {"type": "bookmark",
"login_link": "string",
"icon": "string",
"is_tile_visible": true
}
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"display_name": "string",
"payload": {"type": "bookmark",
"login_link": "string",
"icon": "string",
"is_tile_visible": true,
"application_tile_id": "string"
}
}

Deletes an SSO Config by its 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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"code": "string",
"message": "string",
"details": [{"type": "string"
}
]
}

Associate Identities with an SSO Config

To associate identities to an sso config. 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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Request Body schema: application/json

identity_ids

required

Array of strings [ 1 .. 1000 ] items

IDs of the identities to be added to the sso config.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:addIdentities

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:addIdentities

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:addIdentities

Request samples

Payload

Content type

application/json

{"identity_ids": ["string"
]
}

Response samples

400
401
403
404
500

Content type

application/json

{"code": "bad_request",
"message": "invalid parameters",
"details": [{"type": "FieldViolations",
"field_violations": [{"field": "identity_ids",
"description": "array exceeds 1000 elements"
}
]
}
]
}

Delete Identities from an SSO Config

To delete identities from an sso config. The request must contain at least one and no more than 1000 identities 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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Request Body schema: application/json

identity_ids

required

Array of strings [ 1 .. 1000 ] items

IDs of the identities to be removed from the sso config.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:deleteIdentities

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:deleteIdentities

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:deleteIdentities

Request samples

Payload

Content type

application/json

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

Response samples

400
401
403
404
500

Content type

application/json

{"code": "bad_request",
"message": "invalid parameters",
"details": [{"type": "FieldViolations",
"field_violations": [{"field": "identities_ids",
"description": "array exceeds 1000 elements"
}
]
}
]
}

List Identities Directly and Indirectly Associated With an SSO Config.

To list identities belonging to an sso config. Note that there may be duplicate identities or an empty array in the response, but as long as there is a page_token then pagination should continue.

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.
sso_config_id required	string A unique identifier of the sso configuration

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.

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:listIdentityAssociations

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:listIdentityAssociations

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:listIdentityAssociations

Response samples

200
400
401
403
500

Content type

application/json

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

Returns if an identity is assigned to the SSO config id.

To check if an identity is assigned to the SSO config id, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/sso-configs/$SSO_CONFIG_ID/is-identity-assigned.

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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/sso-configs/{sso_config_id}/is-identity-assigned

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/sso-configs/{sso_config_id}/is-identity-assigned

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/sso-configs/{sso_config_id}/is-identity-assigned

Response samples

200
400
401
403
500

Content type

application/json

{ }

List SSO configs directly and indirectly associated with an identity.

To list sso configs associated with an identity.

This will return all SSO configs that have an association with the specified identity ID. Note that there may be duplicate SSO configs or an empty array in the response, but as long as there is a page_token pagination should continue.

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.
sso_config_id required	string A unique identifier of the sso configuration
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.

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/sso-configs

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/sso-configs

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/sso-configs

Response samples

200
400
401
403
500

Content type

application/json

{"identities": [{"id": "e372db224c06e850",
"realm_id": "8f5bec58229e6f29",
"tenant_id": "0001f1f460b1ace6",
"display_name": "Test Display",
"create_time": "2022-04-12T05:53:07.119Z",
"update_time": "2022-06-16T14:31:03.770Z",
"status": "active",
"traits": {"type": "traits_v0",
"username": "test",
"primary_email_address": "test@example.com",
"secondary_email_address": "string",
"external_id": "string",
"family_name": "string",
"given_name": "string",
"formatted_name": "string",
"middle_name": "string",
"honorific_prefix": "string",
"honorific_suffix": "string",
"nick_name": "string",
"title": "string",
"primary_phone": "string",
"secondary_phone": "string",
"profile_url": "string",
"photo": "string",
"preferred_language": "string",
"locale": "string",
"timezone": "string",
"formatted_address": "string",
"street_address": "string",
"locality": "string",
"region": "string",
"postal_code": "string",
"country": "string",
"user_type": "string",
"employee_number": "string",
"cost_center": "string",
"organization": "string",
"division": "string",
"department": "string",
"manager_id": "string",
"manager_name": "string"
},
"enrollment_status": "ENROLLED",
"group_id": "string",
"group_display_name": "string"
}
],
"next_page_token": "string"
}

Associate Groups with an SSOConfig

To associate groups to an sso config. The request must contain at least one and no more than 1000 group 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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Request Body schema: application/json

group_ids

required

Array of strings [ 1 .. 1000 ] items

IDs of the groups to be added to the sso config.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:addGroups

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:addGroups

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:addGroups

Request samples

Payload

Content type

application/json

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

Response samples

400
401
403
404
500

Content type

application/json

{"code": "bad_request",
"message": "invalid parameters",
"details": [{"type": "FieldViolations",
"field_violations": [{"field": "group_ids",
"description": "array exceeds 1000 elements"
}
]
}
]
}

Delete Groups from an SSO Config

To delete groups from an sso config. The request must contain at least one and no more than 1000 group 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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Request Body schema: application/json

group_ids

required

Array of strings [ 1 .. 1000 ] items

IDs of the groups to be removed from the sso config.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:deleteGroups

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:deleteGroups

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:deleteGroups

Request samples

Payload

Content type

application/json

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

Response samples

400
401
403
404
500

Content type

application/json

{"code": "string",
"message": "string",
"details": [{"type": "string"
}
]
}

List Groups associated with an SSO config.

To list groups associated with an SSO config, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/sso-configs/$SSO_CONFIG_ID/groups.

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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:listGroupAssociations

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:listGroupAssociations

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}:listGroupAssociations

Response samples

200
400
401
403
500

Content type

application/json

{"code": "bad_request",
"message": "invalid parameters",
"details": [{"type": "FieldViolations",
"field_violations": [{"field": "identity_ids",
"description": "array exceeds 1000 elements"
}
]
}
]
}

List SSO Configs associated with a Group.

To list sso configs associated with a group.

This will return all SSO configs that have an association with the specified 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.
sso_config_id required	string A unique identifier of the sso configuration
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.

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"sso_configs": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"display_name": "string",
"payload": {"type": "bookmark",
"login_link": "string",
"icon": "string",
"is_tile_visible": true
}
}
],
"total_size": 1000,
"next_page_token": "string"
}

Check if any of the groups provided are associated with the SSO 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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Request Body schema: application/json
required

group_ids

Array of strings

A group id.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}/is-group-assigned

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}/is-group-assigned

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs/{sso_config_id}/is-group-assigned

Request samples

Payload

Content type

application/json

{"group_ids": ["string"
]
}

Response samples

200
400
401
403
500

Content type

application/json

{ }

Returns the ID of the SSO Config associated with the Application.

Returns the ID of the SSO Config associated with the application.

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.

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/applications/{application_id}/sso-configs-id

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/applications/{application_id}/sso-configs-id

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/applications/{application_id}/sso-configs-id

Response samples

200
400
401
403
500

Content type

application/json

{"sso_config_id": "string"
}

Tests an SSO Config.

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.
sso_config_id required	string A unique identifier of the sso configuration

header Parameters

x-correlation_id

required

string

Correlation ID. If supplied with the request, the response must contain the same value. If not supplied with the request, it is generated by the server and returned in the response.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"identity_providers": [{"identity_provider_id": "123",
"display_name": "Okta IDP",
"is_successful": true,
"status_code": 200
},
{"identity_provider_id": "456",
"display_name": "Ping IDP",
"is_successful": false,
"status_code": 500,
"error_context": "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\" \"http://www.w3.org/TR/html4/strict.dtd\">\n<html>\n<head>\n    <meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n    <meta name=\"robots\" content=\"noindex,nofollow\" />\n\n    <title>zeropw-rolling - Bad Request</title>\n\n    <link rel=\"stylesheet\" type=\"text/css\" href=\"/assets/css/sections/errors-v2.css\">\n\n    <!-- Styles generated from theme -->\n    <link href=\"/api/internal/brand/theme/style-sheet?touch-point=ERROR_PAGE&amp;v=1c5f33b32b86a6a64df6637d07c27a375119d7a8fe54632d87e9ed00b24d9510bd977fcafd928c2991cd5c2dae06d79c\" rel=\"stylesheet\" type=\"text/css\">\n\n    <!-- Favicon from theme -->\n    <link rel=\"shortcut icon\" href=\"/favicon.ico\" type=\"image/x-icon\"/>\n\n\n\n    <style nonce=\"zUfBFwrhQk0UI73zxsAGqg\">\n        #login-bg-image-id {\n            background-image: none\n        }\n    </style>\n</head>\n<body>\n<div id=\"login-bg-image-id\" class=\"login-bg-image tb--background\"></div>\n<div class=\"widget\">\n    <div class=\"container\">\n        <div class=\"header\">\n            <img alt=\"zeropw-rolling\" src=\"https://op1static.oktacdn.com/assets/img/logos/okta-logo.1e146cad5713da744492be95eb0f7793.png\" class=\"org-logo\">\n        </div>\n        <div class=\"illustration\">\n            <!-- Show HTTP error code if exists -->\n            <div class=\"error-code\">400</div>\n            <!-- Show generic error image if not  -->\n        </div>\n        <div class=\"content\">\n            <h2 class=\"o-form-title\">Bad Request</h2>\n            <p class=\"o-form-explain\">Your request resulted in an error. The &#39;redirect_uri&#39; parameter must be a Login redirect URI in the client app settings: https://zeropw-rolling-admin.oktapreview.com/admin/app/oidc_client/instance/0oa24fkg4hed8IxFK0h8#tab-general</p>\n            <a href=\"/\" class=\"button tb--button\">Go to Homepage</a>\n\n            <div class=\"footer\">\n                <a class=\"non-link\">\n                    Technical Details\n                </a> <span class=\"dropdown-arrow\">&#9662;</span>\n                <p class=\"technical-details\">Identity Provider: Unknown, Error Code: invalid_request</p>\n            </div>\n        </div>\n    </div>\n</div>\n</body>\n</html><script type=\"text/javascript\" nonce=\"zUfBFwrhQk0UI73zxsAGqg\">\n    window.addEventListener('load', function(event) {\n        function applyStyle(id, attr) {\n            var el = document.getElementById(id);\n            if (el) {\n                var img = el.getAttribute(attr);\n                if (img) {\n                   el.style[\"background-image\"] = img;\n                }\n            }\n        }\n        applyStyle(\"login-bg-image-id\", \"data-img-url\");\n    });\n</script><style type=\"text/css\" nonce=\"zUfBFwrhQk0UI73zxsAGqg\">\n    #st-app {\n        display: none;\n    }\n</style><span id=\"st-app\">END_USER_APP</span>\n\n<style type=\"text/css\" nonce=\"zUfBFwrhQk0UI73zxsAGqg\">\n        #content-container {\n        width: 1000px;\n        margin: 0 auto;\n        }\n    </style><div id=\"content-container\" class=\"content no-translate\">\n            <h2>\n                Error:&nbsp;The 'redirect_uri' parameter must be a Login redirect URI in the client app settings: https://zeropw-rolling-admin.oktapreview.com/admin/app/oidc_client/instance/0oa24fkg4hed8IxFK0h8#tab-general</h2>\n            <pre></pre>\n    </div>\n"
}
]
}

Launch Mechanisms

Launch mechanisms, or flow type configurations, define which authentication launch mechanisms are enabled and valid for different platforms (Android, iOS, macOS, Windows, Web, Linux, ChromeOS) within a tenant. These configurations control which authentication methods end users can use on different devices and platforms.

Get flow type configuration

Retrieves the flow type configuration for a tenant or creates a default configuration if one does not exist

Authorizations:

None

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": "string",
"tenant_id": "string",
"realm_id": "string",
"create_time": "2019-08-24T14:15:22Z",
"update_time": "2019-08-24T14:15:22Z",
"platform_config": {"android": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"macos": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"ios": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"windows": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"web": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"linux": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"chromeos": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"chromeosweb": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
}
}
}

Update flow type configuration

Updates the flow type configuration for a tenant, note that this will also create a default configuration if one does not exist

Authorizations:

None

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 (UpdateFlowTypeSet) Set of flow type configurations for a platform (update version)
	object (UpdateFlowTypeSet) Set of flow type configurations for a platform (update version)
	object (UpdateFlowTypeSet) Set of flow type configurations for a platform (update version)
	object (UpdateFlowTypeSet) Set of flow type configurations for a platform (update version)
	object (UpdateFlowTypeSet) Set of flow type configurations for a platform (update version)
	object (UpdateFlowTypeSet) Set of flow type configurations for a platform (update version)
	object (UpdateFlowTypeSet) Set of flow type configurations for a platform (update version)
	object (UpdateFlowTypeSet) Set of flow type configurations for a platform (update version)

Responses

Request samples

Payload

Content type

application/json

{"android": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"macos": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"ios": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"windows": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"web": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"linux": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"chromeos": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"chromeosweb": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
}
}

Response samples

Content type

application/json

{"id": "string",
"tenant_id": "string",
"realm_id": "string",
"create_time": "2019-08-24T14:15:22Z",
"update_time": "2019-08-24T14:15:22Z",
"platform_config": {"android": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"macos": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"ios": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"windows": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"web": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"linux": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"chromeos": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
},
"chromeosweb": {"unknown": {"enabled": true,
"valid": true
},
"scheme": {"enabled": true,
"valid": true
},
"embedded": {"enabled": true,
"valid": true
},
"copy": {"enabled": true,
"valid": true
},
"roaming_auth": {"enabled": true,
"valid": true
},
"android_autofill": {"enabled": true,
"valid": true
},
"android_accessibility": {"enabled": true,
"valid": true
},
"pipe": {"enabled": true,
"valid": true
},
"localhost": {"enabled": true,
"valid": true
},
"universal_link": {"enabled": true,
"valid": true
},
"safari_extension": {"enabled": true,
"valid": true
},
"layered_auth_qr_code": {"enabled": true,
"valid": true
},
"secure_localhost": {"enabled": true,
"valid": true
}
}
}
}

Resource Servers

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

Create a New Resource Server

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

required

object (Resource Server)

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

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

List Resource Servers For a Realm

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

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

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

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

Authorizations:

BearerAuth

path Parameters

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

query Parameters

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

Responses

Response samples

Content type

application/json

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

Retrieve an Existing Resource Server

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

Authorizations:

BearerAuth

path Parameters

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}

Response samples

200
401
403
404
500

Content type

application/json

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

Patch a Resource Server

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

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

required

object (Resource Server)

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

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Delete a Resource Server

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

Authorizations:

BearerAuth

path Parameters

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}

Response samples

401
403
404
500

Content type

application/json

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

Roles

Create a New Role

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

Role to be created.

object (Role)

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

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

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles

Response samples

Content type

application/json

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}

Response samples

200
401
403
404
500

Content type

application/json

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

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}

Response samples

401
403
404
409
500

Content type

application/json

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

Assign Members to a Role

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:addMembers

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:addMembers

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:addMembers

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:deleteMembers

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:deleteMembers

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:deleteMembers

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:listMembers

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:listMembers

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:listMembers

Response samples

Content type

application/json

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

Assign Scopes to a Role

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

Authorizations:

BearerAuth

path Parameters

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

Request Body schema: application/json

scopes

required

Array of strings [ 1 .. 1000 ] items

Scopes to be assigned to the role.

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:addScopes

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:addScopes

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:addScopes

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:deleteScopes

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:deleteScopes

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:deleteScopes

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

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

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:listScopes

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:listScopes

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/resource-servers/{resource_server_id}/roles/{role_id}:listScopes

Response samples

Content type

application/json

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

Tokens

List Tokens

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

Authorizations:

BearerAuth

path Parameters

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

query Parameters

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/applications/{application_id}/tokens

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/applications/{application_id}/tokens

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/applications/{application_id}/tokens

Response samples

200
401
403
404
500

Content type

application/json

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

Revoke a Token

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

Authorizations:

BearerAuth

path Parameters

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

Responses

US region API base URL

https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/applications/{application_id}/tokens/{token_id}

EU region API base URL

https://api-eu.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/applications/{application_id}/tokens/{token_id}

US FedRAMP API base URL

https://api.us1.beyondidentity-gov.com/v1/tenants/{tenant_id}/realms/{realm_id}/applications/{application_id}/tokens/{token_id}

Response samples

401
403
404
500

Content type

application/json

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

SCIM

Create a New User

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

Authorizations:

BearerAuth

Request Body schema: application/json

required

object (User)

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

schemas required	Array of strings The list of schemas used to define the user. This must contain only the core User schema ("urn:ietf:params:scim:schemas:core:2.0:User").
externalId	string The provisioning client's unique identifier for the resource.
userName	string non-empty The unique username of the user.
displayName	string non-empty Display name of the User. This name is used for display purposes.
active	boolean Indicator for the user's administrative status. If true, the user has administrative capabilities.
	Array of objects The list containing the user's emails.
	object Definition of the user's name.
	object (EnterpriseUserExtension) Defines attributes commonly used in representing users that belong to, or act on behalf of, a business or enterprise. The enterprise User extension is identified using the following schema URI: "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User".
	object (Meta) Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

201
400
401
403
500

Content type

application/json

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

List All Users

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

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

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

Authorizations:

BearerAuth

query Parameters

filter	string Filter for list methods. Filters follow the SCIM grammar from RFC 7644 Section 3.4.2.2.
count	integer <uint32> >= 0 Default: 0 Specifies the desired maximum number of query results per page. A negative value is treated as 0, which indicates that the response should not contain any resources. Note that the response may include fewer results than the requested count.
startIndex	integer <uint32> >= 1 Default: 1 The 1-based index of the first query result.

Responses

Response samples

200
400
401
403
500

Content type

application/json

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

Retrieve an Existing User

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

Authorizations:

BearerAuth

path Parameters

user_id

required

string non-empty

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

Responses

Response samples

Content type

application/json

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

Patch a User

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

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

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

Authorizations:

BearerAuth

path Parameters

user_id

required

string non-empty

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

Request Body schema: application/json

required

object (User)

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

schemas required	Array of strings The list of schemas used to define the user. This must contain only the core User schema ("urn:ietf:params:scim:schemas:core:2.0:User").
externalId	string The provisioning client's unique identifier for the resource.
userName	string non-empty The unique username of the user.
displayName	string non-empty Display name of the User. This name is used for display purposes.
active	boolean Indicator for the user's administrative status. If true, the user has administrative capabilities.
	Array of objects The list containing the user's emails.
	object Definition of the user's name.
	object (EnterpriseUserExtension) Defines attributes commonly used in representing users that belong to, or act on behalf of, a business or enterprise. The enterprise User extension is identified using the following schema URI: "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User".
	object (Meta) Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Replace a User

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

Authorizations:

BearerAuth

path Parameters

user_id

required

string non-empty

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

Request Body schema: application/json

required

object (User)

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

schemas required	Array of strings The list of schemas used to define the user. This must contain only the core User schema ("urn:ietf:params:scim:schemas:core:2.0:User").
externalId	string The provisioning client's unique identifier for the resource.
userName	string non-empty The unique username of the user.
displayName	string non-empty Display name of the User. This name is used for display purposes.
active	boolean Indicator for the user's administrative status. If true, the user has administrative capabilities.
	Array of objects The list containing the user's emails.
	object Definition of the user's name.
	object (EnterpriseUserExtension) Defines attributes commonly used in representing users that belong to, or act on behalf of, a business or enterprise. The enterprise User extension is identified using the following schema URI: "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User".
	object (Meta) Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

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

Delete a User

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

Authorizations:

BearerAuth

path Parameters

user_id

required

string non-empty

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

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "400",
"scimType": "invalidValue",
"detail": "A required value was missing, or the value specified was not compatible with the operation or attribute type, or resource schema."
}

Create a New Group

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

Authorizations:

BearerAuth

Request Body schema: application/json

required

object (Group)

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

schemas required	Array of strings The list of schemas used to define the group. This must contain the core Group schema ("urn:ietf:params:scim:schemas:core:2.0:Group") and may include the custom Beyond Identity Group schema extension ("urn:scim:schemas:extension:byndid:1.0:Group").
displayName	string non-empty The unique display name of the group. This name is used for display purposes.
	object (Meta) Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

201
400
401
403
500

Content type

application/json

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

List All Groups

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

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

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

Members will not be returned with the group.

Authorizations:

BearerAuth

query Parameters

filter	string Filter for list methods. Filters follow the SCIM grammar from RFC 7644 Section 3.4.2.2.
count	integer <uint32> >= 0 Default: 0 Specifies the desired maximum number of query results per page. A negative value is treated as 0, which indicates that the response should not contain any resources. Note that the response may include fewer results than the requested count.
startIndex	integer <uint32> >= 1 Default: 1 The 1-based index of the first query result.

Responses

Response samples

200
400
401
403
500

Content type

application/json

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

Retrieve an existing group

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

Authorizations:

BearerAuth

path Parameters

group_id

required

string non-empty

ID of the group.

Responses

Response samples

Content type

application/json

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

Patch a Group

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

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

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

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

Authorizations:

BearerAuth

path Parameters

group_id

required

string non-empty

ID of the group.

Request Body schema: application/json

required

object (Group)

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

schemas required	Array of strings The list of schemas used to define the group. This must contain the core Group schema ("urn:ietf:params:scim:schemas:core:2.0:Group") and may include the custom Beyond Identity Group schema extension ("urn:scim:schemas:extension:byndid:1.0:Group").
displayName	string non-empty The unique display name of the group. This name is used for display purposes.
	object (Meta) Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Payload

Content type

application/json

Example

Replace DisplayName

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

Response samples

Content type

application/json

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

Delete a Group

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

Authorizations:

BearerAuth

path Parameters

group_id

required

string non-empty

ID of the group.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "400",
"scimType": "invalidValue",
"detail": "A required value was missing, or the value specified was not compatible with the operation or attribute type, or resource schema."
}

List All Resource Types

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

Authorizations:

BearerAuth

Responses

Response samples

200
500

Content type

application/json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"
],
"id": "User",
"name": "User",
"description": "User Account",
"endpoint": "/Users",
"schema": "urn:ietf:params:scim:schemas:core:2.0:User",
"schemaExtensions": [ ]
},
{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"
],
"id": "Group",
"name": "Group",
"description": "User Groups",
"endpoint": "/Groups",
"schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
"schemaExtensions": [{"required": false,
"schema": "urn:scim:schemas:extension:byndid:1.0:Group"
}
]
}
],
"itemsPerPage": 1000,
"startIndex": 1,
"totalResults": 2
}

List All Schemas

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

Authorizations:

BearerAuth

Responses

Response samples

200
500

Content type

application/json

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

Retrieve the Service Provider Configuration

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

Authorizations:

BearerAuth

Responses

Response samples

200
500

Content type

application/json

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