Skip to main content
API docs by Redocly

Beyond Identity Secure Workforce Admin API (2.4.1)

Download OpenAPI specification:Download

E-mail: [email protected]

Introduction

The Beyond Identity Secure Workforce Admin API defines methods for administrative duties for your Beyond Identity tenant.

This API is currently in the early-access stage with limited endpoints implemented. We encourage feedback and suggestions through [email protected].

Authentication

All Beyond Identity API endpoints require authentication using an access token. The access token is generated through OAuth 2.0, using the client credentials flow. Follow these steps:

  1. Navigate to the Beyond Identity Secure Workforce Admin Console.
  2. Under the Settings tab in the side panel, select the API Access tab and create a set of client credentials.
  3. Use the client ID and client secret to exchange the client credentials for an access token. You can use the following cURL call below:
curl https://api.byndid.com/v2/oauth2/token \
  -X POST \
  -u "$CLIENT_ID:$CLIENT_SECRET" --basic \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

Alternatively, an access token may also be generated via the Admin Console.

  1. Navigate to the Beyond Identity Secure Workforce Admin Console.
  2. Under the Settings tab in the side panel, select the API Access tab and create a set of client credentials.
  3. Next, select the created client credentials, navigate to the Tokens tab, and click Create token.

Once you've obtained the access token, you must provide it in the Authorization header of any API request.

curl https://api.byndid.com/v2/... \
  -X $HTTP_METHOD -H "Authorization: Bearer $TOKEN"

Rate Limiting

The Beyond Identity public API is subject to rate limiting to ensure a consistent quality of service for our customers. Rate limits are enforced per tenant, if you are experiencing issues with the default rate limits provided, please refer to our support page.

When a request exceeds a rate limit, our application server returns an HTTP 429 status code and RateLimit-* headers, as described in RateLimit Header Fields for HTTP. Example response:

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 30
RateLimit-Remaining: 0
RateLimit-Reset: 7

Authorization

Each method will have associated scopes. See the Authorizations portion within each method to see the scopes.

The access token used must contain all scopes for the method to be able to access the endpoint.

Requests and Responses

When interacting with the Beyond Identity Secure Workforce Admin API, all requests must be made over HTTPS.

The Beyond Identity API is 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 can be read-only and immutable. For example, system-generated IDs are both read-only and immutable.

  • A read-only field is provided only in the response.
  • An immutable field is assigned only once and cannot be changed.

Create a new resource

Create requests use the POST method and include the necessary attributes to create a new resource. Create operations return the created resource in the response.

Retrieve resources

Retrieve requests use the GET method. You can retrieve a single resource or a collection of resources. When retrieving a collection of resources, the response includes an array of JSON objects keyed on the plural name of the requested resource.

Update resources

Update requests use the PATCH method. Update operations support partial updating, so you can specify only the attributes you want to update. Update operations return the updated resource in the response.

Delete resources

Delete requests use the DELETE method, which returns an empty response instead of returning the resource in the response.

Example response for a user

{
  "id": "b60a8085-2508-46d8-8ef6-aba593afaac2",
  "tenant_id": "acme-corp",
  "username": "alice.acmecorp"
  "display_name": "Alice Acmecorp",
  "create_time": "2022-06-22T21:46:08.930278Z",
  "update_time": "2022-06-22T21:46:08.930278Z",
  ...
}

Example response for a collection of users

{
  "users": [
    {
      "id": "b60a8085-2508-46d8-8ef6-aba593afaac2",
      "tenant_id": "acme-corp",
      "username": "alice.acmecorp"
      "display_name": "Alice Acmecorp",
      "create_time": "2022-06-22T21:46:08.930278Z",
      "update_time": "2022-06-22T21:46:08.930278Z",
      ...
    }
  ],
  "total_size": 1
}

HTTP statuses

The API returns standard HTTP statuses and error codes.

Code range Description
200 The request was fulfilled successfully with no errors.
400 There was an issue with the request that the client may address. For example, client errors may indicate that the request was missing proper authorization or was malformed.
500 The server encountered an internal issue and could not fulfill the request.

All error responses include a JSON object with a code field and a message field.

  • code has a human-readable name for the HTTP status code, and
  • message has a high-level description of the error.

The error can also have additional details that the client can use 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 or 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'll 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": "user not found"
  "details": [
    {
      "type": "ResourceInfo",
      "resource_type": "User",
      "id": "348afd29-f265-4eee-9451-1fcf71832e77",
      "description": "user not found"
    }
  ],
}

Invalid parameters example

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

Too many requests example

If the caller has exceeded their rate limit they may receive a 429 error. This response does not include any body.

HTTP/1.1 429 Too Many Requests

Users

A user is a member of an organization using Beyond Identity.

Create a new user

To create a user, send a POST request to /v2/users. Values in the request body for read-only fields get ignored. If the request conflicts with an existing resource, you'll receive a 409 error. When the user gets created, they'll receive a Beyond Identity enrollment email sent to the email address in the request.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object (User)

A user is a member of an organization that uses Beyond Identity.

external_id
string

A required unique identifier for the user within the tenant.

email_address
string

A required email address serving as primary contact for user.

username
string

A required username for the user.

display_name
string

A required human-readable name for the user that is used for display purposes.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "f7277b07-4a9e-4f84-9839-cd3082a6b8c3",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "last_auth_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "external_id": "0001f1f460b1ace6",
  • "email_address": "[email protected]",
  • "username": "alice.acmecorp",
  • "display_name": "Alice Acmecorp",
  • "state": "ACTIVE",
  • "source": "scim",
  • "has_active_passkey": true
}

List all users for a tenant

To list all users for a tenant, send a GET request to /v2/users.

The response will have up to 1000 items. The response will be empty if the page size is not specified (i.e., the default). By default, the list is in ascending order by create_time. The maximum and default page sizes are subject to change.

When paginating, use the skip parameter as the offset.

When filtering, the response will only show users that satisfy this filter. The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

The supported fields and their supported operations are:

  • id (eq, ne, co, sw, ew)
  • email_address (eq, ne, co, sw, ew)
  • external_id (eq, ne, co, sw, ew)
  • username (eq, ne, co, sw, ew)
  • display_name (eq, ne, co, sw, ew)
  • state (eq, ne, co, sw, ew)
  • source (eq, ne, co, sw, ew)
  • last_auth_time (pr, eq, ne, gt, lt, ge, le)
  • has_active_passkey (eq, ne)

When sorting, use the order_by parameter. It's a comma-delimited list of attributes. Currently, the following fields are supported:

  • display_name
  • username
  • email_address
  • status
  • source
  • last_auth_time

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Authorizations:
BearerAuth
query Parameters
page_size
integer <uint32> >= 0

The number of items returned per page. The response may include this exact number or fewer. If omitting this value, the response returns the default number of results the method allows.

skip
integer <uint32> >= 0
Default: 0

Number of items to skip. This is the zero-based index of the first result.

filter
string

Filter query for responses.

The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

See individual methods for the supported attributes and operations.

Ex. name co "alice"

order_by
string

A comma-delimited list of attributes to sort results.

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Ex. name desc

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "total_size": 1
}

Retrieve an existing user

To retrieve an existing user for a tenant, send a GET request to /v2/users/$USER_ID.

Authorizations:
BearerAuth
path Parameters
user_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a user.

Responses

Response samples

Content type
application/json
{
  • "id": "f7277b07-4a9e-4f84-9839-cd3082a6b8c3",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "last_auth_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "external_id": "0001f1f460b1ace6",
  • "email_address": "[email protected]",
  • "username": "alice.acmecorp",
  • "display_name": "Alice Acmecorp",
  • "state": "ACTIVE",
  • "source": "scim",
  • "has_active_passkey": true
}

Update a user

To update only specific attributes of an existing user, send a PATCH request to /v2/users/$USER_ID. Values in the request body for immutable or read-only fields get ignored. Fields omitted from the request body will be left unchanged. If the request conflicts with an existing resource, you'll receive a 409 error.

Authorizations:
BearerAuth
path Parameters
user_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a user.

Responses

Response samples

Content type
application/json
{
  • "id": "f7277b07-4a9e-4f84-9839-cd3082a6b8c3",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "last_auth_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "external_id": "0001f1f460b1ace6",
  • "email_address": "[email protected]",
  • "username": "alice.acmecorp",
  • "display_name": "Alice Acmecorp",
  • "state": "ACTIVE",
  • "source": "scim",
  • "has_active_passkey": true
}

Delete a user

To delete a user for a tenant, send a DELETE request to /v2/users/$USER_ID. A successful request will receive a 200 status code with nothing in the response's body. This indicates that the request was processed successfully.

Authorizations:
BearerAuth
path Parameters
user_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a user.

Responses

Response samples

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

Retrieve groups for a user

Get a list of groups to which a user belongs.

Authorizations:
BearerAuth
path Parameters
user_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a user.

query Parameters
page_size
integer <uint32> >= 0

The number of items returned per page. The response may include this exact number or fewer. If omitting this value, the response returns the default number of results the method allows.

skip
integer <uint32> >= 0
Default: 0

Number of items to skip. This is the zero-based index of the first result.

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "total_size": 1000
}

Groups

Create a new group

To create a group, send a POST request to /v2/groups. Values in the request body for read-only attributes get ignored.

If the requested group name is already in use, you'll receive a 409 error.

Note that this endpoint does not support creating permission groups. If the request attempts to create a group with the name of a permission group, you will receive a 403 error.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object (Group)

A group is a collection of members within an organization that uses Beyond Identity.

name
string

A required unique name for the group within the tenant.

description
string

A required description for the group within the tenant.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "name": "Acme Group",
  • "description": "Members of the Acme Group",
  • "source": "scim"
}

List all groups for a tenant

To list all groups for a tenant, send a GET request to /v2/groups. Note that this endpoint excludes permission groups.

The response will have up to 1000 items. The response will be empty if the page size is not specified (i.e., the default). By default, the list is in ascending order by create_time. The maximum and default page sizes are subject to change.

When paginating, use the skip parameter as the offset.

When filtering, the response will only show users that satisfy this filter. The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)

The supported fields and their supported operations are:

  • id (eq, ne, co, sw, ew)
  • name (eq, ne, co, sw, ew)
  • description (eq, ne, co, sw, ew)
  • source (eq, ne, co, sw, ew)

When sorting, use the order_by parameter. It's a comma-delimited list of attributes. Currently, the following fields are supported:

  • name
  • source

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Authorizations:
BearerAuth
query Parameters
page_size
integer <uint32> >= 0

The number of items returned per page. The response may include this exact number or fewer. If omitting this value, the response returns the default number of results the method allows.

skip
integer <uint32> >= 0
Default: 0

Number of items to skip. This is the zero-based index of the first result.

filter
string

Filter query for responses.

The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

See individual methods for the supported attributes and operations.

Ex. name co "alice"

order_by
string

A comma-delimited list of attributes to sort results.

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Ex. name desc

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "total_size": 1
}

Retrieve an existing group

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

Note that this endpoint does not support access to permission groups. If the request attempts to access a permission group, you'll receive a 403 error.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

Responses

Response samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "name": "Acme Group",
  • "description": "Members of the Acme Group",
  • "source": "scim"
}

Patch a group

To update only specific attributes of an existing group, send a PATCH request to /v2/groups/$GROUP_ID. Values in the request body for read-only attributes get ignored. Fields omitted from the request body will be left unchanged.

If the updated name of the group is already in use, you'll receive a 409 error.

Note that this endpoint does not support updates to permission groups. If the request attempts to use the name of a permission group or attempts to update a permission group, you'll receive a 403 error.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

Request Body schema: application/json
required
object (Group)

A group is a collection of members within an organization that uses Beyond Identity.

name
string

A required unique name for the group within the tenant.

description
string

A required description for the group within the tenant.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "name": "Acme Group",
  • "description": "Members of the Acme Group",
  • "source": "scim"
}

Delete a group

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

A successful request will receive a 200 status code with nothing in the response's body. This indicates that the request was processed successfully.

Note that this endpoint does not support deleting permission groups. If the request attempts to delete a permission group, you'll receive a 403 error.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

Responses

Response samples

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

List all users for a group

To list all users belonging to a group, send a GET request to /v2/groups/$GROUP_ID:listUsers.

The response will have up to 1000 items. The response will be empty if the page size is not specified (i.e., the default). By default, the list is in ascending order by create_time. The maximum and default page sizes are subject to change.

When paginating, use the skip parameter as the offset.

When filtering, the response will only show users that satisfy this filter. The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

The supported fields and their supported operations are:

  • id (eq, ne, co, sw, ew)
  • email_address (eq, ne, co, sw, ew)
  • external_id (eq, ne, co, sw, ew)
  • username (eq, ne, co, sw, ew)
  • display_name (eq, ne, co, sw, ew)
  • state (eq, ne, co, sw, ew)
  • source (eq, ne, co, sw, ew)
  • last_auth_time (pr, eq, ne, gt, lt, ge, le)
  • has_active_passkey (eq, ne)

When sorting, use the order_by parameter. It's a comma-delimited list of attributes. Currently, the following fields are supported:

  • display_name
  • username
  • email_address
  • status
  • source
  • last_auth_time

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

query Parameters
page_size
integer <uint32> >= 0

The number of items returned per page. The response may include this exact number or fewer. If omitting this value, the response returns the default number of results the method allows.

skip
integer <uint32> >= 0
Default: 0

Number of items to skip. This is the zero-based index of the first result.

filter
string

Filter query for responses.

The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

See individual methods for the supported attributes and operations.

Ex. name co "alice"

order_by
string

A comma-delimited list of attributes to sort results.

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Ex. name desc

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "total_size": 1
}

Add users to a group

To add users to a group, send a POST request to /v2/groups/$GROUP_ID:addUsers. The request may include up to 1000 users to add. Users which already belong to the group will be ignored.

Note that this endpoint does not support adding users to permission groups. If the request attempts to add users to a permission group, you'll receive a 403 error.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

Request Body schema: application/json
id
string

ID of the group.

user_ids
Array of strings [ 1 .. 1000 ] items

IDs of the users to be added to the group.

Responses

Request samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "user_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "name": "Acme Group",
  • "description": "Members of the Acme Group",
  • "source": "scim"
}

Delete users from a group

To delete users from a group, send a POST request to /v2/groups/$GROUP_ID:deleteUsers. The request may contain up to 1000 users to delete. Users which already do not belong to the group will be ignored.

Note that this endpoint does not support deleting users from permission groups. If the request attempts to delete users from a permission group, you'll receive a 403 error.

Authorizations:
BearerAuth
path Parameters
group_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique identifier for a group.

Request Body schema: application/json
id
string

ID of the group.

user_ids
Array of strings [ 1 .. 1000 ] items

IDs of the users to be deleted from the group.

Responses

Request samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "user_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "25f94daf-63d8-4b40-b0ea-4843971d1d8e",
  • "create_time": "2022-04-12T05:53:07.119Z",
  • "update_time": "2022-06-16T14:31:03.770Z",
  • "tenant_id": "acme-corp",
  • "name": "Acme Group",
  • "description": "Members of the Acme Group",
  • "source": "scim"
}

BindingJobs

Create a new credential binding job

To create a binding job, send a POST request to /v2/binding-jobs. Values in the request body for read-only attributes get ignored.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object (BindingJob)

A binding job tracks the process of binding a new credential for a user.

ttl_seconds
integer <uint32> [ 60 .. 900 ]
Default: 60

Number of seconds until the binding job expires. This must be between 1 minute (60 seconds) and 15 minutes (900 seconds). This field is used only if the expire_time on the requested binding job is unspecified. This field defaults to 1 minute (60 seconds).

Responses

Request samples

Content type
application/json
Example
{
  • "binding_job": {
    }
}

Response samples

Content type
application/json
{
  • "id": "66d36cf5-96df-4fa3-a5d0-36d0aa8487c3",
  • "tenant_id": "acme-corp",
  • "user_id": "11819414-9000-4700-af07-2743c02d68ca",
  • "issuer_user_id": "4dfb7751-46a9-4bd6-a591-a5941cb24eba",
  • "delivery_method": "SHORT_CODE",
  • "short_code_delivery_details": {
    }
}

Passkeys

List Passkeys for a tenant

Returns a list of passkeys for a given tenant and realm.

The supported filter operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

The supported fields and their supported operations are:

  • id (eq, ne, co, sw, ew)
  • date_last_auth (pr, eq, ne, gt, lt, ge, le)
  • platform (eq, ne, co, sw, ew)
  • platform_pr (pr)
  • sdk (eq, ne, co, sw, ew)
  • major (eq, ne, co, sw, ew)
  • minor (eq, ne, co, sw, ew)
  • patch (eq, ne, co, sw, ew)
  • is_rooted (eq, ne)
  • is_jailbroken (eq, ne)
  • hardware_serial_number (eq, ne, co, sw, ew)
  • serial_number (pr)
  • app_version (eq, ne, co, sw, ew)
  • vul_firewall (eq, ne)
  • vul_rooted (eq, ne)
  • vul_biometric (eq, ne)
  • vul_password (eq, ne)
  • vul_tpm (eq, ne)
  • user_name (eq, ne, co, sw, ew)
  • hostname (eq, ne, co, sw, ew)
  • user_status (eq, ne, co, sw, ew)

Additionally fuzzy search is available on the "username" and "hostname" fields using the "search" and the "eq" operator:

  • search (eq)

When sorting, use the order_by parameter. It's a comma-delimited list of attributes. Currently, the following fields are supported:

  • date_last_auth
  • hostname
  • user_name
  • platform
  • sdk
  • major
  • minor
  • patch

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Authorizations:
BearerAuth
query Parameters
page_size
integer <uint32> >= 0

The number of items returned per page. The response may include this exact number or fewer. If omitting this value, the response returns the default number of results the method allows.

skip
integer <uint32> >= 0
Default: 0

Number of items to skip. This is the zero-based index of the first result.

filter
string

Filter query for responses.

The syntax follows the SCIM grammar from RFC7644 Section 3.4.2.2.

The supported operations are:

  • pr (present)
  • eq (equals)
  • ne (not equals)
  • co (contains)
  • sw (starts with)
  • ew (ends with)
  • gt (greater than)
  • lt (less than)
  • ge (greater than or equal to)
  • le (less than or equal to)

See individual methods for the supported attributes and operations.

Ex. name co "alice"

order_by
string

A comma-delimited list of attributes to sort results.

The default sorting order per attribute is ascending. Therefore, if you want descending order, append the " desc" suffix to the attribute name.

Ex. name desc

Responses

Response samples

Content type
application/json
{
  • "passkeys": [
    ],
  • "total_size": 1000
}

Delete a passkey

Deletes a passkey from the current tenant and realm.

Remember don't revoke your own passkey, or you may be locked out.

This end point always returns 200 even if the passkey doesn't exist.

Authorizations:
BearerAuth
path Parameters
passkey_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique passkey.

Responses

Response samples

Content type
application/json
{
  • "code": "bad_request",
  • "message": "invalid request"
}

Get tags associated with a passkey

Returns a list of tags and their ID, such as device name, vulnerability, OS version, etc. associated with a passkey.

Authorizations:
BearerAuth
path Parameters
passkey_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique passkey.

Responses

Response samples

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

Replace the tags associated with a new list of passkeys

Replaces the values of current tags associated with a passkey with a provided set of tag values. This list will replace all existing tags associated with a passkey. For example, if a provided tag does not include an id, a new tag value will be created or an existing tag will be used if it already exists.

Authorizations:
BearerAuth
path Parameters
passkey_id
required
string
Example: 25f94daf-63d8-4b40-b0ea-4843971d1d8e

A unique passkey.

Request Body schema: application/json
required
Array of objects
Array
id
string
name
string

Responses

Request samples

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

Response samples

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

SCIM

Create a New User

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

Authorizations:
BearerAuth
Request Body schema: application/json
required
object (User)

A user represents a human entity as defined by RFC 7643 Section 4.1.

schemas
required
Array of strings

The list of schemas used to define the user. This must contain only the core User schema ("urn:ietf:params:scim:schemas:core:2.0:User").

externalId
string

The provisioning client's unique identifier for the resource.

userName
string non-empty

The unique username of the user. The value of this field will be returned as the subject of an OIDC ID Token.

displayName
string non-empty

Display name of the User. This name is used for display purposes.

active
boolean

Indicator for the user's administrative status. If true, the user has administrative capabilities.

Array of objects

The list containing the user's emails.

object

Definition of the user's name.

object (Meta)

Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "2819c223-7f76-453a-919d-413861904646",
  • "userName": "bjensen",
  • "externalId": "bjensen",
  • "name": {
    },
  • "emails": []
}

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "2819c223-7f76-453a-919d-413861904646",
  • "externalId": "bjensen",
  • "userName": "bjensen",
  • "displayName": "Ms. Barbara J Jensen III",
  • "active": true,
  • "emails": [],
  • "meta": {
    }
}

List All Users

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

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

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

Authorizations:
BearerAuth
query Parameters
filter
string

Filter for list methods.

Filters follow the SCIM grammar from RFC 7644 Section 3.4.2.2.

count
integer <uint32> >= 0
Default: 0

Specifies the desired maximum number of query results per page. A negative value is treated as 0, which indicates that the response should not contain any resources. Note that the response may include fewer results than the requested count.

startIndex
integer <uint32> >= 0
Default: 0

The 1-based index of the first query result.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "Resources": [
    ],
  • "itemsPerPage": 1000,
  • "startIndex": 1,
  • "totalResults": 1
}

Retrieve an Existing User

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

Authorizations:
BearerAuth
path Parameters
user_id
required
string non-empty

ID of the user.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "ed9fcce6-ec82-458e-ae58-e2d975cfc32d",
  • "externalId": "external-id-abcdef",
  • "userName": "test_user",
  • "displayName": "Test User",
  • "active": true,
  • "emails": [],
  • "name": {
    },
  • "meta": {
    }
}

Patch a User

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

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

Currently, only "add" and "replace" operations are supported for users. The "add" operation may be used to assign the user's primary email. However, "path" is ignored for all other PATCH operations, meaning that all other operation values are expected to specify a complex value in the form of a user resource.

Authorizations:
BearerAuth
path Parameters
user_id
required
string non-empty

ID of the user.

Request Body schema: application/json
required
object (User)

A user represents a human entity as defined by RFC 7643 Section 4.1.

schemas
required
Array of strings

The list of schemas used to define the user. This must contain only the core User schema ("urn:ietf:params:scim:schemas:core:2.0:User").

externalId
string

The provisioning client's unique identifier for the resource.

userName
string non-empty

The unique username of the user. The value of this field will be returned as the subject of an OIDC ID Token.

displayName
string non-empty

Display name of the User. This name is used for display purposes.

active
boolean

Indicator for the user's administrative status. If true, the user has administrative capabilities.

Array of objects

The list containing the user's emails.

object

Definition of the user's name.

object (Meta)

Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Content type
application/json
{
  • "schemas": [
    ],
  • "Operations": [
    ]
}

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "2819c223-7f76-453a-919d-413861904646",
  • "externalId": "bjensen",
  • "userName": "bjensen",
  • "displayName": "Ms. Barbara J Jensen III",
  • "active": true,
  • "emails": [],
  • "meta": {
    }
}

Replace a User

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

Authorizations:
BearerAuth
path Parameters
user_id
required
string non-empty

ID of the user.

Request Body schema: application/json
required
object (User)

A user represents a human entity as defined by RFC 7643 Section 4.1.

schemas
required
Array of strings

The list of schemas used to define the user. This must contain only the core User schema ("urn:ietf:params:scim:schemas:core:2.0:User").

externalId
string

The provisioning client's unique identifier for the resource.

userName
string non-empty

The unique username of the user. The value of this field will be returned as the subject of an OIDC ID Token.

displayName
string non-empty

Display name of the User. This name is used for display purposes.

active
boolean

Indicator for the user's administrative status. If true, the user has administrative capabilities.

Array of objects

The list containing the user's emails.

object

Definition of the user's name.

object (Meta)

Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "2819c223-7f76-453a-919d-413861904646",
  • "userName": "bjensen",
  • "externalId": "bjensen",
  • "displayName": "Ms. Barbara J Jensen III",
  • "name": {
    },
  • "emails": []
}

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "2819c223-7f76-453a-919d-413861904646",
  • "externalId": "bjensen",
  • "userName": "bjensen",
  • "displayName": "Ms. Barbara J Jensen III",
  • "active": true,
  • "emails": [],
  • "meta": {
    }
}

Delete a User

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

Authorizations:
BearerAuth
path Parameters
user_id
required
string non-empty

ID of the user.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "status": "400",
  • "scimType": "invalidValue",
  • "detail": "A required value was missing, or the value specified was not compatible with the operation or attribute type, or resource schema."
}

Create a New Group

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

Authorizations:
BearerAuth
Request Body schema: application/json
required
object (Group)

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

schemas
required
Array of strings

The list of schemas used to define the group. This must contain the core Group schema ("urn:ietf:params:scim:schemas:core:2.0:Group") and may include the custom Beyond Identity Group schema extension ("urn:scim:schemas:extension:byndid:1.0:Group").

displayName
string non-empty

The unique display name of the group. This name is used for display purposes.

Array of objects

The list of the group's members.

object

The Beyond Identity Group schema extension.

object (Meta)

Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "22e7c78c-39ff-4501-8ed4-32d0479e54c1",
  • "displayName": "Test Group",
  • "members": [
    ],
  • "urn:scim:schemas:extension:byndid:1.0:Group": {
    }
}

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "22e7c78c-39ff-4501-8ed4-32d0479e54c1",
  • "displayName": "Test Group",
  • "members": [
    ],
  • "urn:scim:schemas:extension:byndid:1.0:Group": {
    },
  • "meta": {
    }
}

List All Groups

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

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

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

Note that this method excludes RBAC permission groups used for the Admin Console.

Authorizations:
BearerAuth
query Parameters
filter
string

Filter for list methods.

Filters follow the SCIM grammar from RFC 7644 Section 3.4.2.2.

count
integer <uint32> >= 0
Default: 0

Specifies the desired maximum number of query results per page. A negative value is treated as 0, which indicates that the response should not contain any resources. Note that the response may include fewer results than the requested count.

startIndex
integer <uint32> >= 0
Default: 0

The 1-based index of the first query result.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "Resources": [
    ],
  • "itemsPerPage": 1000,
  • "startIndex": 1,
  • "totalResults": 1
}

Retrieve an existing group

To retrieve an existing group, send a GET request to /Groups/$GROUP_ID. Note that this method cannot be used to retrieve RBAC permission groups used for the Admin Console.

Authorizations:
BearerAuth
path Parameters
group_id
required
string non-empty

ID of the group.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "ed9fcce6-ec82-458e-ae58-e2d975cfc32d",
  • "displayName": "Help Desk",
  • "members": [],
  • "urn:scim:schemas:extension:byndid:1.0:Group": {
    },
  • "meta": {
    }
}

Patch a Group

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

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

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

Note that this method cannot be used to update any groups which were not created by SCIM, e.g. RBAC permission groups or other groups created through the Admin Console.

Authorizations:
BearerAuth
path Parameters
group_id
required
string non-empty

ID of the group.

Request Body schema: application/json
required
object (Group)

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

schemas
required
Array of strings

The list of schemas used to define the group. This must contain the core Group schema ("urn:ietf:params:scim:schemas:core:2.0:Group") and may include the custom Beyond Identity Group schema extension ("urn:scim:schemas:extension:byndid:1.0:Group").

displayName
string non-empty

The unique display name of the group. This name is used for display purposes.

Array of objects

The list of the group's members.

object

The Beyond Identity Group schema extension.

object (Meta)

Resource metadata as defined in RFC 7643 Section 3.1. This attribute is only populated on responses and is ignored on requests.

Responses

Request samples

Content type
application/json
{
  • "schemas": [
    ],
  • "Operations": [
    ]
}

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "id": "22e7c78c-39ff-4501-8ed4-32d0479e54c1",
  • "displayName": "Test Group",
  • "members": [
    ],
  • "urn:scim:schemas:extension:byndid:1.0:Group": {
    },
  • "meta": {
    }
}

Delete a Group

To delete a group, send a DELETE request to /Groups/$GROUP_ID. Note that this method cannot be used to delete any groups which were not created by SCIM, e.g. RBAC permission groups or other groups created through the Admin Console.

Authorizations:
BearerAuth
path Parameters
group_id
required
string non-empty

ID of the group.

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "status": "400",
  • "scimType": "invalidValue",
  • "detail": "A required value was missing, or the value specified was not compatible with the operation or attribute type, or resource schema."
}

List All Resource Types

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

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "Resources": [
    ],
  • "itemsPerPage": 1000,
  • "startIndex": 1,
  • "totalResults": 2
}

List All Schemas

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

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "Resources": [
    ],
  • "itemsPerPage": 1000,
  • "startIndex": 1,
  • "totalResults": 3
}

Retrieve the Service Provider Configuration

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

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "schemas": [
    ],
  • "authenticationSchemes": [
    ],
  • "bulk": {
    },
  • "changePassword": {
    },
  • "documentationUri": "",
  • "etag": {
    },
  • "filter": {
    },
  • "patch": {
    },
  • "sort": {
    }
}