Beyond Identity

Beyond Identity Realms API

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

GitHub OpenAPI

Operations 5

POST /v1/tenants/{tenant_id}/realms Create a New Realm #
GET /v1/tenants/{tenant_id}/realms List Realms for a Tenant #
GET /v1/tenants/{tenant_id}/realms/{realm_id} Retrieve an Existing Realm #
PATCH /v1/tenants/{tenant_id}/realms/{realm_id} Patch a Realm #
DELETE /v1/tenants/{tenant_id}/realms/{realm_id} Delete a Realm #

Documentation

📖
Documentation
https://developer.beyondidentity.com/docs/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/beyond-identity/refs/heads/main/openapi/beyond-identity-realms-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/beyond-identity/refs/heads/main/json-schema/beyond-identity-identity-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/beyond-identity/refs/heads/main/json-schema/beyond-identity-credential-schema.json

Other Resources

🔗
Examples
https://raw.githubusercontent.com/api-evangelist/beyond-identity/refs/heads/main/examples/beyond-identity-create-identity-example.json
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/beyond-identity/refs/heads/main/examples/beyond-identity-credential-binding-job-example.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/beyond-identity-realms-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

beyond-identity-realms-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Beyond Identity Secure Access Realms API
  version: 1.7.0
  contact:
    email: support@beyondidentity.com
  description: '# Introduction


    **NOTE:** To determine if you are accessing the Secure Access Platform, check the URL of your Admin Console.'
servers:
- url: https://api-us.beyondidentity.com
  description: US region API base URL
- url: https://api-eu.beyondidentity.com
  description: EU region API base URL
- url: https://api.us1.beyondidentity-gov.com/
  description: US FedRAMP API base URL
security:
- BearerAuth: []
tags:
- name: Realms
  description: A realm is a unique administrative domain within a tenant. Realms may be used to define multiple development environments or for isolated administrative domains.
paths:
  /v1/tenants/{tenant_id}/realms:
    post:
      tags:
      - Realms
      operationId: CreateRealm
      summary: Create a New Realm
      description: 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.
      security:
      - BearerAuth:
        - realms:create
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      requestBody:
        content:
          application/json:
            schema:
              title: Create Realm Request
              description: Request for CreateRealm.
              type: object
              properties:
                realm:
                  $ref: '#/components/schemas/Realm'
              required:
              - realm
      responses:
        '200':
          description: 'The response will be a JSON object containing the standard attributes associated with a realm.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Realm'
              examples:
                Success:
                  value:
                    id: 19a95130480dfa79
                    tenant_id: 0001f1f460b1ace6
                    display_name: Test Realm
                    classification: SECURE_WORKFORCE
                    create_time: '2022-05-18T18:00:01.167Z'
                    update_time: '2022-05-19T14:23:01.327Z'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Malformed Request:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/patch/responses/400/content/application~1json/examples/Malformed%20Request'
                Invalid Parameters:
                  value:
                    code: bad_request
                    message: invalid parameters
                    details:
                    - type: FieldViolations
                      field_violations:
                      - field: realm.display_name
                        description: empty string
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Missing Authorization:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/401/content/application~1json/examples/Missing%20Authorization'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Insufficient Authorization:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/403/content/application~1json/examples/Insufficient%20Authorization'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Internal Error:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/500/content/application~1json/examples/Internal%20Error'
    get:
      tags:
      - Realms
      operationId: ListRealms
      summary: List Realms for a Tenant
      description: '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.'
      security:
      - BearerAuth:
        - realms:read
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/page_token'
      - $ref: '#/components/parameters/skip'
      responses:
        '200':
          description: 'The response will be a JSON object with keys for `realms` and `total_size`. `realms` will be set to an array of realm objects, each of which contain the standard realm attributes. `total_size` will be set to the total number of items matched by the list request. If there are more items to be returned by the requested query, the response will also contain a key called `next_page_token`.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRealmsResponse'
              examples:
                Success:
                  value:
                    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
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid Parameters:
                  value:
                    code: bad_request
                    message: invalid parameters
                    details:
                    - type: FieldViolations
                      field_violations:
                      - field: page_token
                        description: invalid page token
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Missing Authorization:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/401/content/application~1json/examples/Missing%20Authorization'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Insufficient Authorization:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/403/content/application~1json/examples/Insufficient%20Authorization'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Internal Error:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/500/content/application~1json/examples/Internal%20Error'
  /v1/tenants/{tenant_id}/realms/{realm_id}:
    get:
      tags:
      - Realms
      operationId: GetRealm
      summary: Retrieve an Existing Realm
      description: To retrieve an existing realm, send a GET request to `/v1/tenants/$TENANT_ID/realms/$REALM_ID`.
      security:
      - BearerAuth:
        - realms:read
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      - $ref: '#/components/parameters/realm_id'
      responses:
        '200':
          description: 'The response will be a JSON object containing the standard attributes associated with a realm.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Realm'
              examples:
                Success:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms/post/responses/200/content/application~1json/examples/Success'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Missing Authorization:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/401/content/application~1json/examples/Missing%20Authorization'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Insufficient Authorization:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/403/content/application~1json/examples/Insufficient%20Authorization'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Realm Not Found:
                  value:
                    code: not_found
                    message: realm not found
                    details:
                    - type: ResourceInfo
                      resource_type: Realm
                      id: 19a95130480dfa79
                      description: realm not found
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Internal Error:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/500/content/application~1json/examples/Internal%20Error'
    patch:
      tags:
      - Realms
      operationId: UpdateRealm
      summary: Patch a Realm
      description: 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.
      security:
      - BearerAuth:
        - realms:update
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      - $ref: '#/components/parameters/realm_id'
      requestBody:
        content:
          application/json:
            schema:
              title: Update Realm Request
              description: Request for UpdateRealm.
              type: object
              properties:
                realm:
                  $ref: '#/components/schemas/Realm'
              required:
              - realm
            examples:
              Update Display Name:
                value:
                  realm:
                    display_name: Test Realm
      responses:
        '200':
          description: 'The response will be a JSON object containing the standard attributes associated with a realm.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Realm'
              examples:
                Success:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms/post/responses/200/content/application~1json/examples/Success'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Malformed Request:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/patch/responses/400/content/application~1json/examples/Malformed%20Request'
                Invalid Parameters:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms/post/responses/400/content/application~1json/examples/Invalid%20Parameters'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Missing Authorization:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/401/content/application~1json/examples/Missing%20Authorization'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Insufficient Authorization:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/403/content/application~1json/examples/Insufficient%20Authorization'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Realm Not Found:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D/get/responses/404/content/application~1json/examples/Realm%20Not%20Found'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Internal Error:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/500/content/application~1json/examples/Internal%20Error'
    delete:
      tags:
      - Realms
      operationId: DeleteRealm
      summary: Delete a Realm
      description: '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.'
      security:
      - BearerAuth:
        - realms:delete
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      - $ref: '#/components/parameters/realm_id'
      responses:
        '200':
          description: The action was successful and the response body is empty.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Missing Authorization:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/401/content/application~1json/examples/Missing%20Authorization'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Insufficient Authorization:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/403/content/application~1json/examples/Insufficient%20Authorization'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Realm Not Found:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D/get/responses/404/content/application~1json/examples/Realm%20Not%20Found'
        '409':
          description: Conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Realm Has Resources:
                  value:
                    code: conflict
                    message: realm has children
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Internal Error:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D/get/responses/500/content/application~1json/examples/Internal%20Error'
components:
  parameters:
    page_token:
      name: page_token
      in: query
      description: '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.

        '
      schema:
        type: string
    realm_id:
      name: realm_id
      in: path
      description: A unique identifier for a realm.
      required: true
      schema:
        type: string
        example: 19a95130480dfa79
    page_size:
      name: page_size
      in: query
      description: '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.

        '
      schema:
        type: integer
        format: uint32
        minimum: 0
    skip:
      name: skip
      in: query
      description: 'Number of items to skip. This is the zero-based index of the first result.

        '
      schema:
        type: integer
        format: uint32
        minimum: 0
        default: 0
    tenant_id:
      name: tenant_id
      in: path
      description: A unique identifier for a tenant.
      required: true
      schema:
        type: string
        example: 000176d94fd7b4d1
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: 'Human-readable HTTP status code name, stylized as lower snake case (e.g. bad_request).

            '
        message:
          type: string
          description: 'Human-readable message describing the error.

            '
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
      required:
      - code
      - message
    Realm:
      title: Realm
      type: object
      description: 'A realm is a unique administrative domain within a tenant. Realms may be used to define multiple development environments or for isolated administrative domains.

        '
      properties:
        id:
          type: string
          description: 'A unique identifier for the realm. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the tenant.

            '
          readOnly: true
          example: 19a95130480dfa79
        tenant_id:
          type: string
          description: 'A unique identifier of the realm''s tenant. This is automatically set on creation. This field is immutable and read-only.

            '
          readOnly: true
          example: 0001f1f460b1ace6
        display_name:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[^{}[\]<>;:?\\/|*^%$#=~`!]*$
          description: 'A human-readable name for the realm. This name is used for display purposes.

            '
          example: Test Realm
        classification:
          type: string
          description: Classification of the realm. Can be either SECURE_WORFORCE or SECURE_CUSTOMER
          example: SECURE_CUSTOMER
        create_time:
          type: string
          format: date-time
          description: 'A time value given in ISO8601 combined date and time format that represents when the realm was created. This is automatically generated on creation. This field is read-only.

            '
          readOnly: true
          example: '2022-05-18T18:00:01.167Z'
        update_time:
          type: string
          format: date-time
          description: 'A time value given in ISO8601 combined date and time format that represents when the realm was last updated. This is automatically updated when the realm is updated. This field is read-only.

            '
          readOnly: true
          example: '2022-05-19T14:23:01.327Z'
    ErrorDetail:
      title: Error Detail
      description: 'Additional details for errors designed to support client applications.

        '
      type: object
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
          description: Type of the error detail.
      required:
      - type
    ListRealmsResponse:
      title: List Realms Response
      description: Response for ListRealms.
      type: object
      properties:
        realms:
          type: array
          items:
            $ref: '#/components/schemas/Realm'
          maxItems: 200
          description: An unordered array of realms corresponding to the request.
        total_size:
          type: integer
          format: uint32
          description: 'Total number of results returned by the operation. This value may be larger than the number of resources returned, such as when returning a single page where multiple pages are available.

            '
          example: 1000
        next_page_token:
          type: string
          description: 'Token used to fetch the next set of results. If this field is omitted, there are no subsequent pages.

            '
      required:
      - realms
      - total_size
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'See the [Authentication](#section/Authentication) section for details.

        '