Beyond Identity API (1.7.0)
Download OpenAPI specification:Download
The Beyond Identity API defines methods for managing realms, directories, credentials, and applications.
All of the functionality available in the Beyond Identity Admin Console is also available through the API.
This API is currently in the early-access stage and is under active development. Feedback and suggestions are encouraged and should be directed to the Beyond Identity Developer Slack Channel.
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"
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
}
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"
}
],
}
],
}
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:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
Responses
Response samples
- 200
- 401
- 403
- 500
{- "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:
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. | ||
|
Responses
Request samples
- Payload
{- "tenant": {
- "display_name": "Test Tenant"
}
}
Response samples
- 200
- 400
- 401
- 403
- 500
{- "id": "000176d94fd7b4d1",
- "display_name": "Test Tenant",
- "create_time": "2022-01-28T12:00:02.423Z",
- "update_time": "2022-04-19T15:17:21.186Z"
}
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:
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. | ||
|
Responses
Request samples
- Payload
{- "realm": {
- "display_name": "Test Realm"
}
}
Response samples
- 200
- 400
- 401
- 403
- 500
{- "id": "19a95130480dfa79",
- "tenant_id": "0001f1f460b1ace6",
- "display_name": "Test Realm",
- "create_time": "2022-05-18T18:00:01.167Z",
- "update_time": "2022-05-19T14:23:01.327Z"
}
List Realms for a Tenant
To list all realms for a tenant, send a GET request to
/v1/tenants/$TENANT_ID/realms
.
The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of realms in the response. Note that the maximum and default page sizes are subject to change.
When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.
Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.
Authorizations:
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
{- "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:
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
{- "id": "19a95130480dfa79",
- "tenant_id": "0001f1f460b1ace6",
- "display_name": "Test Realm",
- "create_time": "2022-05-18T18:00:01.167Z",
- "update_time": "2022-05-19T14:23:01.327Z"
}
Patch a Realm
To update only specific attributes of an existing realm, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID
. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.
Authorizations:
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. | ||
|
Responses
Request samples
- Payload
{- "realm": {
- "display_name": "Test Realm"
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "19a95130480dfa79",
- "tenant_id": "0001f1f460b1ace6",
- "display_name": "Test Realm",
- "create_time": "2022-05-18T18:00:01.167Z",
- "update_time": "2022-05-19T14:23:01.327Z"
}
Delete a Realm
To delete a realm, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID
. To be deleted, a realm must not have any identities, groups, or roles. All associated resources must first be deleted or you will receive a 409 error.
A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.
Authorizations:
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
{- "code": "unauthorized",
- "message": "unauthorized"
}
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:
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. | ||||
|
Responses
Request samples
- Payload
{- "group": {
- "display_name": "Realm Administrators",
- "description": "A group of realm administrators."
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "81490afab171aef0",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "display_name": "Realm Administrators",
- "description": "A group of realm administrators.",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
List Groups for a Realm
To list all groups for a realm, send a GET request to
/v1/tenants/$TENANT_ID/realms/$REALM_ID/groups
.
The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of groups in the response. Note that the maximum and default page sizes are subject to change.
When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.
Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.
Authorizations:
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
- 200
- 400
- 401
- 403
- 404
- 500
{- "groups": [
- {
- "id": "81490afab171aef0",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "display_name": "Realm Administrators",
- "description": "A group of realm administrators.",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
], - "total_size": 1
}
Retrieve an Existing Group
To retrieve an existing group, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID
.
Authorizations:
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
{- "id": "81490afab171aef0",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "display_name": "Realm Administrators",
- "description": "A group of realm administrators.",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
Patch a Group
To update only specific attributes of an existing group, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID
. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.
Authorizations:
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. | ||||
|
Responses
Request samples
- Payload
{- "group": {
- "display_name": "Realm Administrators"
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "81490afab171aef0",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "display_name": "Realm Administrators",
- "description": "A group of realm administrators.",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
Delete a Group
To delete a group, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID
. To be deleted, a group must not have any members. Any existing members must first be deleted or you will receive a 409 error.
A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.
Authorizations:
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
{- "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:
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
{- "identity_ids": [
- "e372db224c06e850",
- "3a28d4f28b57cc93"
]
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "81490afab171aef0",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "display_name": "Realm Administrators",
- "description": "A group of realm administrators.",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
Delete Members from a Group
To delete members from a group, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID:deleteMembers
. The request must contain at least one and no more than 1000 identity IDs.
Authorizations:
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
{- "identity_ids": [
- "e372db224c06e850",
- "3a28d4f28b57cc93"
]
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "81490afab171aef0",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "display_name": "Realm Administrators",
- "description": "A group of realm administrators.",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
List Members for a Group
To list members belonging to a group, send a GET request to
/v1/tenants/$TENANT_ID/realms/$REALM_ID/groups/$GROUP_ID:listMembers
.
The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of members in the response. Note that the maximum and default page sizes are subject to change.
When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.
Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.
Authorizations:
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
- 200
- 400
- 401
- 403
- 404
- 500
{- "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:
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
- 200
- 400
- 401
- 403
- 404
- 409
- 500
{- "roles": [
- {
- "id": "fb785d40cbe4fc0d",
- "resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
- "realm_id": "bb26e0e8ecdef843",
- "tenant_id": "00010036778ce59f",
- "description": "Help Desk",
- "display_name": "Customer support personnel.",
- "create_time": "2023-02-14T18:18:58.332Z",
- "update_time": "2023-02-14T18:18:58.332Z"
}
], - "total_size": 1
}
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:
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. | ||||||
|
Responses
Request samples
- Payload
{- "identity": {
- "display_name": "Test Identity",
- "traits": {
- "type": "traits_v0",
- "username": "test",
- "primary_email_address": "test@example.com"
}
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 409
- 500
{- "id": "e372db224c06e850",
- "realm_id": "8f5bec58229e6f29",
- "tenant_id": "0001f1f460b1ace6",
- "display_name": "Test Identity",
- "create_time": "2022-04-12T05:53:07.119Z",
- "update_time": "2022-06-16T14:31:03.770Z",
- "traits": {
- "type": "traits_v0",
- "username": "test",
- "primary_email_address": "test@example.com"
}
}
List Identities for a Realm
To list identities for a realm, send a GET request to
/v1/tenants/$TENANT_ID/realms/$REALM_ID/identities
.
The response will only contain identities matching the filter in the
request. If no filter is provided, the request will match all identities in
the realm. Currently, the only supported filter is
traits.username eq "$USERNAME"
.
The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of identities in the response. Note that the maximum and default page sizes are subject to change.
When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The filter is also maintained by the page token but it may not be overridden. If specified, the request filter must match the filter maintained by the page token, otherwise you will receive a 400 error. The skip is not maintained by the page token and must be specified on each subsequent request.
Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.
Authorizations:
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
- 200
- 400
- 401
- 403
- 404
- 500
{- "identities": [
- {
- "id": "e372db224c06e850",
- "realm_id": "8f5bec58229e6f29",
- "tenant_id": "0001f1f460b1ace6",
- "display_name": "Test Identity",
- "create_time": "2022-04-12T05:53:07.119Z",
- "update_time": "2022-06-16T14:31:03.770Z",
- "traits": {
- "type": "traits_v0",
- "username": "test",
- "primary_email_address": "test@example.com"
}
}
], - "total_size": 1
}
Retrieve an Existing Identity
To retrieve an existing identity, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID
.
Authorizations:
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
{- "id": "e372db224c06e850",
- "realm_id": "8f5bec58229e6f29",
- "tenant_id": "0001f1f460b1ace6",
- "display_name": "Test Identity",
- "create_time": "2022-04-12T05:53:07.119Z",
- "update_time": "2022-06-16T14:31:03.770Z",
- "traits": {
- "type": "traits_v0",
- "username": "test",
- "primary_email_address": "test@example.com"
}
}
Patch an Identity
To update only specific attributes of an existing identity, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID
. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.
If the request conflicts with an existing resource, you will receive a 409 error.
Authorizations:
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. | ||||||
|
Responses
Request samples
- Payload
{- "identity": {
- "display_name": "Test Identity",
- "traits": {
- "type": "traits_v0",
- "primary_email_address": "test@example.com"
}
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 409
- 500
{- "id": "e372db224c06e850",
- "realm_id": "8f5bec58229e6f29",
- "tenant_id": "0001f1f460b1ace6",
- "display_name": "Test Identity",
- "create_time": "2022-04-12T05:53:07.119Z",
- "update_time": "2022-06-16T14:31:03.770Z",
- "traits": {
- "type": "traits_v0",
- "username": "test",
- "primary_email_address": "test@example.com"
}
}
Delete an Identity
To delete an identity, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID
. To be deleted, an identity must not be a member of any groups or roles. The identity must must first be removed from all groups and roles or you will receive a 409 error.
A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
identity_id required | string Example: e372db224c06e850 A unique identifier for an identity. |
Responses
Response samples
- 401
- 403
- 404
- 409
- 500
{- "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:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
identity_id required | string Example: e372db224c06e850 A unique identifier for an identity. |
query Parameters
page_size | integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method. |
page_token | string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified. |
skip | integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result. |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "groups": [
- {
- "id": "81490afab171aef0",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "display_name": "Realm Administrators",
- "description": "A group of realm administrators.",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
], - "total_size": 1
}
List Role Memberships for an Identity
To list the roles to which an identity is assigned, send a GET request to
/v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID:listRoles
.
The request must include the resource_server_id
query parameter specifying
the resource server on which to filter the roles. If the specified resource
server does not exist, you will receive a 409 error.
The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of roles in the response. Note that the maximum and default page sizes are subject to change.
When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.
Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
identity_id required | string Example: e372db224c06e850 A unique identifier for an identity. |
query Parameters
resource_server_id | string non-empty The unique identifier of the resource server used to filter roles. |
page_size | integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method. |
page_token | string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified. |
skip | integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result. |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 409
- 500
{- "roles": [
- {
- "id": "fb785d40cbe4fc0d",
- "resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
- "realm_id": "bb26e0e8ecdef843",
- "tenant_id": "00010036778ce59f",
- "description": "Help Desk",
- "display_name": "Customer support personnel.",
- "create_time": "2023-02-14T18:18:58.332Z",
- "update_time": "2023-02-14T18:18:58.332Z"
}
], - "total_size": 1
}
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:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
identity_id required | string Example: e372db224c06e850 A unique identifier for an identity. |
query Parameters
page_size | integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method. |
page_token | string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified. |
skip | integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result. |
Responses
Response samples
- 200
- 400
- 401
- 403
- 500
{- "credentials": [
- {
- "id": "81490afab171aef0",
- "identity_id": "e85de356dc78843a",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "state": "ACTIVE",
- "csr_type": "JWT",
- "jwk_json": "{\"crv\":\"P-256\",\"kty\":\"EC\",\"x\":\"2MRhz05PJPq3BUfB18AT3HqgWEkI3VpWUg1MWi8rz1g\",\"y\":\"YtvLYwGEqYQaoDVok2fVziJT4fu7DFPz3hy96FTAelQ\"}",
- "jwk_thumbprint": "UW-uVNL0mP1vcLjHrTBxibNgCEe_PD0HIsE3FrbYjPA=",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
], - "total_size": 1
}
Retrieve an Existing Credential
To retrieve an existing credential, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credentials/$CREDENTIAL_ID
.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
identity_id required | string Example: e372db224c06e850 A unique identifier for an identity. |
credential_id required | string Example: b5a31610800dda18 A unique identifier for a credential. |
Responses
Response samples
- 200
- 401
- 403
- 404
- 500
{- "id": "81490afab171aef0",
- "identity_id": "e85de356dc78843a",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "state": "ACTIVE",
- "csr_type": "JWT",
- "jwk_json": "{\"crv\":\"P-256\",\"kty\":\"EC\",\"x\":\"2MRhz05PJPq3BUfB18AT3HqgWEkI3VpWUg1MWi8rz1g\",\"y\":\"YtvLYwGEqYQaoDVok2fVziJT4fu7DFPz3hy96FTAelQ\"}",
- "jwk_thumbprint": "UW-uVNL0mP1vcLjHrTBxibNgCEe_PD0HIsE3FrbYjPA=",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
Revoke a Credential
To revoke a credential, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credentials/$CREDENTIAL_ID:revoke
.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
identity_id required | string Example: e372db224c06e850 A unique identifier for an identity. |
credential_id required | string Example: b5a31610800dda18 A unique identifier for a credential. |
Responses
Response samples
- 200
- 401
- 403
- 404
- 500
{- "id": "81490afab171aef0",
- "identity_id": "e85de356dc78843a",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "state": "ACTIVE",
- "csr_type": "JWT",
- "jwk_json": "{\"crv\":\"P-256\",\"kty\":\"EC\",\"x\":\"2MRhz05PJPq3BUfB18AT3HqgWEkI3VpWUg1MWi8rz1g\",\"y\":\"YtvLYwGEqYQaoDVok2fVziJT4fu7DFPz3hy96FTAelQ\"}",
- "jwk_thumbprint": "UW-uVNL0mP1vcLjHrTBxibNgCEe_PD0HIsE3FrbYjPA=",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
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:
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. | ||||||||
|
Responses
Request samples
- Payload
{- "job": {
- "delivery_method": "RETURN",
- "authenticator_config_id": "67bb0acf12e5c899"
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 422
- 500
{- "credential_binding_job": {
- "id": "c4fc2d753ca22b14",
- "realm_id": "cdf4862dc4d49791",
- "tenant_id": "000183a77dd50fa9",
- "identity_id": "87fabad6956c6d4b",
- "delivery_method": "RETURN",
- "state": "LINK_SENT",
- "authenticator_config_id": "67bb0acf12e5c899",
- "expire_time": "2022-03-21T03:42:52.905Z",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-03-15T05:55:23.823Z"
},
}
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:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
identity_id required | string Example: e372db224c06e850 A unique identifier for an identity. |
query Parameters
page_size | integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method. |
page_token | string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified. |
skip | integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result. |
Responses
Response samples
- 200
- 400
- 401
- 403
- 500
{- "credential_binding_jobs": [
- {
- "id": "81490afab171aef0",
- "identity_id": "e85de356dc78843a",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "credential_id": "9802966246819b35",
- "delivery_method": "EMAIL",
- "state": "COMPLETE",
- "authenticator_config_id": "67bb0acf12e5c899",
- "expire_time": "2022-03-21T03:42:52.905Z",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-03-15T05:55:23.823Z"
}
], - "total_size": 1
}
Retrieve an Existing Credential Binding Job
To retrieve an existing credential binding job, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID
/credential-binding-jobs/$CREDENTIAL_BINDING_JOB_ID`.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
identity_id required | string Example: e372db224c06e850 A unique identifier for an identity. |
credential_binding_job_id required | string Example: 5c4137af5e70413a A unique identifier for a credential binding job. |
Responses
Response samples
- 200
- 401
- 403
- 404
- 500
{- "id": "81490afab171aef0",
- "identity_id": "e85de356dc78843a",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "credential_id": "9802966246819b35",
- "delivery_method": "EMAIL",
- "state": "COMPLETE",
- "authenticator_config_id": "67bb0acf12e5c899",
- "expire_time": "2022-03-21T03:42:52.905Z",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-03-15T05:55:23.823Z"
}
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:
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. | |||||||||||||
|
Responses
Request samples
- Payload
{- "theme": {
- "email_realm_name": "Realm Administrators",
- "button_color": "#4673D3",
- "button_text_color": "#FFFFFF"
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 409
- 500
{- "id": "88ef08fb-c3f9-44e2-b174-fbb239e1dc47",
- "tenant_id": "f36448f2ff094881",
- "realm_id": "aa6aabe6989bc4a5",
- "email_realm_name": "Realm Administrators",
- "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:
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
{- "id": "88ef08fb-c3f9-44e2-b174-fbb239e1dc47",
- "tenant_id": "f36448f2ff094881",
- "realm_id": "aa6aabe6989bc4a5",
- "email_realm_name": "Realm Administrators",
- "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:
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
{- "id": "88ef08fb-c3f9-44e2-b174-fbb239e1dc47",
- "tenant_id": "f36448f2ff094881",
- "realm_id": "aa6aabe6989bc4a5",
- "email_realm_name": "Realm Administrators",
- "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:
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. | |||||||||||||
|
Responses
Request samples
- Payload
{- "theme": {
- "email_realm_name": "Realm Administrators"
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "88ef08fb-c3f9-44e2-b174-fbb239e1dc47",
- "tenant_id": "f36448f2ff094881",
- "realm_id": "aa6aabe6989bc4a5",
- "email_realm_name": "Realm Administrators",
- "create_time": "2022-07-28T18:00:00.000Z",
- "button_color": "#4673D3",
- "button_text_color": "#FFFFFF"
}
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:
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. | ||||||||
|
Responses
Request samples
- Payload
{- "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"
], - "token_configuration": {
- "subject_field": "id",
- "expires_after": 86400,
- "token_signing_algorithm": "RS256"
}, - "pkce": "disabled",
- "token_format": "self_contained"
}
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "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"
], - "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:
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
- 200
- 400
- 401
- 403
- 404
- 500
{- "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"
], - "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:
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
{- "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"
], - "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:
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. | ||||||||
|
Responses
Request samples
- Payload
{- "application": {
- "display_name": "Pet Application"
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "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"
], - "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:
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
{- "code": "unauthorized",
- "message": "unauthorized"
}
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:
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. | ||||
|
Responses
Request samples
- Payload
{- "authenticator_config": {
- "display_name": "Pet Authenticator Configuration",
- "config": {
- "type": "embedded",
}
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
- "realm_id": "caf2ff640497591a",
- "tenant_id": "00011f1183c67b69",
- "display_name": "Pet Authenticator Configuration",
- "config": {
- "type": "embedded",
- "invocation_type": "automatic",
- "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:
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
- 200
- 400
- 401
- 403
- 404
- 500
{- "authenticator_configs": [
- {
- "id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
- "realm_id": "caf2ff640497591a",
- "tenant_id": "00011f1183c67b69",
- "display_name": "Pet Authenticator Configuration",
- "config": {
- "invocation_type": "automatic",
- "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:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
authenticator_config_id required | string Example: 73731b7f-eb76-4143-9b4b-81a720385f5a A unique identifier for an authenticator configuration. |
Responses
Response samples
- 200
- 401
- 403
- 404
- 500
{- "id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
- "realm_id": "caf2ff640497591a",
- "tenant_id": "00011f1183c67b69",
- "display_name": "Pet Authenticator Configuration",
- "config": {
- "type": "embedded",
- "invocation_type": "automatic",
- "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:
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. | ||||
|
Responses
Request samples
- Payload
{- "authenticator_config": {
- "display_name": "Pet Authenticator Configuration",
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "73731b7f-eb76-4143-9b4b-81a720385f5a",
- "realm_id": "caf2ff640497591a",
- "tenant_id": "00011f1183c67b69",
- "display_name": "Pet Authenticator Configuration",
- "config": {
- "type": "embedded",
- "invocation_type": "automatic",
- "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:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
authenticator_config_id required | string Example: 73731b7f-eb76-4143-9b4b-81a720385f5a A unique identifier for an authenticator configuration. |
Responses
Response samples
- 401
- 403
- 404
- 500
{- "code": "unauthorized",
- "message": "unauthorized"
}
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:
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. | ||||||
|
Responses
Request samples
- Payload
{- "resource_server": {
- "display_name": "Pet API",
- "scopes": [
- "pets:read",
- "pets:write"
]
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
- "realm_id": "caf2ff640497591a",
- "tenant_id": "00011f1183c67b69",
- "display_name": "Pet API",
- "is_managed": false,
- "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:
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
- 200
- 400
- 401
- 403
- 404
- 500
{- "resource_servers": [
- {
- "id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
- "realm_id": "caf2ff640497591a",
- "tenant_id": "00011f1183c67b69",
- "display_name": "Pet API",
- "is_managed": false,
- "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:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
Responses
Response samples
- 200
- 401
- 403
- 404
- 500
{- "id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
- "realm_id": "caf2ff640497591a",
- "tenant_id": "00011f1183c67b69",
- "display_name": "Pet API",
- "is_managed": false,
- "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:
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. | ||||||
|
Responses
Request samples
- Payload
{- "resource_server": {
- "display_name": "Pet API"
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "84db69f5-48a8-4c11-8cda-1bae3a73f07e",
- "realm_id": "caf2ff640497591a",
- "tenant_id": "00011f1183c67b69",
- "display_name": "Pet API",
- "is_managed": false,
- "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:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
Responses
Response samples
- 401
- 403
- 404
- 500
{- "code": "unauthorized",
- "message": "unauthorized"
}
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:
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. | |||||
|
Responses
Request samples
- Payload
{- "role": {
- "display_name": "Help Desk",
- "description": "Customer support personnel."
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "fb785d40cbe4fc0d",
- "resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
- "realm_id": "bb26e0e8ecdef843",
- "tenant_id": "00010036778ce59f",
- "description": "Help Desk",
- "display_name": "Customer support personnel.",
- "create_time": "2023-02-14T18:18:58.332Z",
- "update_time": "2023-02-14T18:18:58.332Z"
}
List Roles for a Resource Server
To list all roles for a resource server, send a GET request to
/v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles
.
The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of roles in the response. Note that the maximum and default page sizes are subject to change.
When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.
Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
query Parameters
page_size | integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method. |
page_token | string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified. |
skip | integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result. |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "roles": [
- {
- "id": "fb785d40cbe4fc0d",
- "resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
- "realm_id": "bb26e0e8ecdef843",
- "tenant_id": "00010036778ce59f",
- "description": "Help Desk",
- "display_name": "Customer support personnel.",
- "create_time": "2023-02-14T18:18:58.332Z",
- "update_time": "2023-02-14T18:18:58.332Z"
}
], - "total_size": 1
}
Retrieve an Existing Role
To retrieve an existing role, send a GET request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID
.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
role_id required | string Example: fb785d40cbe4fc0d A unique identifier for a role. |
Responses
Response samples
- 200
- 401
- 403
- 404
- 500
{- "id": "fb785d40cbe4fc0d",
- "resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
- "realm_id": "bb26e0e8ecdef843",
- "tenant_id": "00010036778ce59f",
- "description": "Help Desk",
- "display_name": "Customer support personnel.",
- "create_time": "2023-02-14T18:18:58.332Z",
- "update_time": "2023-02-14T18:18:58.332Z"
}
Patch a Role
To update only specific attributes of an existing role, send a PATCH request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID
. Values in the request body for immutable or read-only fields will be ignored. Fields that are omitted from the request body will be left unchanged.
Authorizations:
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. | ||||
|
Responses
Request samples
- Payload
{- "role": {
- "display_name": "Help Desk"
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "fb785d40cbe4fc0d",
- "resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
- "realm_id": "bb26e0e8ecdef843",
- "tenant_id": "00010036778ce59f",
- "description": "Help Desk",
- "display_name": "Customer support personnel.",
- "create_time": "2023-02-14T18:18:58.332Z",
- "update_time": "2023-02-14T18:18:58.332Z"
}
Delete a Role
To delete a role, send a DELETE request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID
. To be deleted, a role must not have any scopes or members. Any existing scopes and members must first be deleted or you will receive a 409 error.
A successful request will receive a 200 status code with no body in the response. This indicates that the request was processed successfully.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
role_id required | string Example: fb785d40cbe4fc0d A unique identifier for a role. |
Responses
Response samples
- 401
- 403
- 404
- 409
- 500
{- "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:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
role_id required | string Example: fb785d40cbe4fc0d A unique identifier for a role. |
Request Body schema: application/json
group_ids | Array of strings [ 1 .. 1000 ] items IDs of the groups to be assigned to the role. |
identity_ids | Array of strings [ 1 .. 1000 ] items IDs of the identities to be assigned to the role. |
Responses
Request samples
- Payload
{- "group_ids": [
- "e372db224c06e850"
], - "identity_ids": [
- "3a28d4f28b57cc93"
]
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "fb785d40cbe4fc0d",
- "resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
- "realm_id": "bb26e0e8ecdef843",
- "tenant_id": "00010036778ce59f",
- "description": "Help Desk",
- "display_name": "Customer support personnel.",
- "create_time": "2023-02-14T18:18:58.332Z",
- "update_time": "2023-02-14T18:18:58.332Z"
}
Unassign Members from a Role
To unassign members from a role, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:deleteMembers
. The request must contain at least one group ID or identity ID and must not contain more than 1000 group IDs or 1000 identity IDs.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
role_id required | string Example: fb785d40cbe4fc0d A unique identifier for a role. |
Request Body schema: application/json
group_ids | Array of strings [ 1 .. 1000 ] items IDs of the groups to be unassigned from the role. |
identity_ids | Array of strings [ 1 .. 1000 ] items IDs of the identities to be unassigned from the role. |
Responses
Request samples
- Payload
{- "group_ids": [
- "e372db224c06e850"
], - "identity_ids": [
- "3a28d4f28b57cc93"
]
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "fb785d40cbe4fc0d",
- "resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
- "realm_id": "bb26e0e8ecdef843",
- "tenant_id": "00010036778ce59f",
- "description": "Help Desk",
- "display_name": "Customer support personnel.",
- "create_time": "2023-02-14T18:18:58.332Z",
- "update_time": "2023-02-14T18:18:58.332Z"
}
List Members for a Role
To list members assigned to a role, send a GET request to
/v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:listMembers
.
The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of members in the response. Note that the maximum and default page sizes are subject to change.
When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.
Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
role_id required | string Example: fb785d40cbe4fc0d A unique identifier for a role. |
query Parameters
groups_page_size | integer <uint32> >= 0 Number of groups returned per page for ListRoleMembers. The response will include at most this many groups but may include fewer. If this value is omitted, the response will return the default number of groups allowed by ListRoleMembers. |
groups_skip | integer <uint32> >= 0 Default: 0 Number of groups to skip for ListRoleMembers. This is the zero-based index of the first group result. |
identities_page_size | integer <uint32> >= 0 Number of identities returned per page for ListRoleMembers. The response will include at most this many identities but may include fewer. If this value is omitted, the response will return the default number of identities allowed by ListRoleMembers. |
identities_skip | integer <uint32> >= 0 Default: 0 Number of identities to skip for ListRoleMembers. This is the zero-based index of the first identity result. |
page_token | string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified. |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "groups": [
- {
- "id": "81490afab171aef0",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "display_name": "Realm Administrators",
- "description": "A group of realm administrators.",
- "create_time": "2022-03-14T03:42:52.905Z",
- "update_time": "2022-06-14T05:55:23.823Z"
}
], - "total_groups_size": 1,
- "identities": [
- {
- "id": "e372db224c06e850",
- "realm_id": "7df92e4a38ba0993",
- "tenant_id": "0001b42d80372976",
- "display_name": "Test Identity",
- "create_time": "2022-04-12T05:53:07.119Z",
- "update_time": "2022-06-16T14:31:03.770Z",
- "traits": {
- "type": "traits_v0",
- "username": "test",
- "primary_email_address": "test@example.com"
}
}
], - "total_identities_size": 1
}
Assign Scopes to a Role
To assign scopes to a role, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:addScopes
. The request must contain at least one and no more than 1000 scopes.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
role_id required | string Example: fb785d40cbe4fc0d A unique identifier for a role. |
Request Body schema: application/json
scopes required | Array of strings [ 1 .. 1000 ] items Scopes to be assigned to the role. |
Responses
Request samples
- Payload
{- "scopes": [
- "identities:read"
]
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "fb785d40cbe4fc0d",
- "resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
- "realm_id": "bb26e0e8ecdef843",
- "tenant_id": "00010036778ce59f",
- "description": "Help Desk",
- "display_name": "Customer support personnel.",
- "create_time": "2023-02-14T18:18:58.332Z",
- "update_time": "2023-02-14T18:18:58.332Z"
}
Unassign Scopes from a Role
To unassign scopes from a role, send a POST request to /v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:deleteScopes
. The request must contain at least one and no more than 1000 scopes.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
role_id required | string Example: fb785d40cbe4fc0d A unique identifier for a role. |
Request Body schema: application/json
scopes required | Array of strings [ 1 .. 1000 ] items Scopes to be removed from the role. |
Responses
Request samples
- Payload
{- "scopes": [
- "identities:read"
]
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "id": "fb785d40cbe4fc0d",
- "resource_server_id": "7b5a4325-00e0-4379-bd7b-3e5e7e30b09e",
- "realm_id": "bb26e0e8ecdef843",
- "tenant_id": "00010036778ce59f",
- "description": "Help Desk",
- "display_name": "Customer support personnel.",
- "create_time": "2023-02-14T18:18:58.332Z",
- "update_time": "2023-02-14T18:18:58.332Z"
}
List Scopes for a Role
To list scopes assigned to a role, send a GET request to
/v1/tenants/$TENANT_ID/realms/$REALM_ID/resource-servers/$RESOURCE_SERVER_ID/roles/$ROLE_ID:listScopes
.
The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of scopes in the response. Note that the maximum and default page sizes are subject to change.
When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The skip is not maintained by the page token and must be specified on each subsequent request.
Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior.
Authorizations:
path Parameters
tenant_id required | string Example: 000176d94fd7b4d1 A unique identifier for a tenant. |
realm_id required | string Example: 19a95130480dfa79 A unique identifier for a realm. |
resource_server_id required | string Example: 84db69f5-48a8-4c11-8cda-1bae3a73f07e A unique identifier for a resource server. |
role_id required | string Example: fb785d40cbe4fc0d A unique identifier for a role. |
query Parameters
page_size | integer <uint32> >= 0 Number of items returned per page. The response will include at most this many results but may include fewer. If this value is omitted, the response will return the default number of results allowed by the method. |
page_token | string Token to retrieve the subsequent page of the previous request. All other parameters to the list endpoint should match the original request that provided this token unless otherwise specified. |
skip | integer <uint32> >= 0 Default: 0 Number of items to skip. This is the zero-based index of the first result. |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
{- "scopes": [
- "identities:read"
], - "total_size": 1
}
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:
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:
|
principal_id | string A unique identifier for a principal. This might be an application ID or an identity ID depending on the type of principal. |
Responses
Response samples
- 200
- 401
- 403
- 404
- 500
{- "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:
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 |
Responses
Response samples
- 401
- 403
- 404
- 500
{- "code": "unauthorized",
- "message": "unauthorized"
}
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:
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. | ||||||||||||||||
|
Responses
Request samples
- Payload