Beyond Identity Credentials API

openapi: 3.2.0
info:
  title: Beyond Identity Secure Access Credentials 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: Credentials
  description: A credential is also known as a passkey. This is the public-private key pair that belongs to an identity.
paths:
  /v1/tenants/{tenant_id}/realms/{realm_id}/identities/{identity_id}/credentials:
    get:
      tags:
      - Credentials
      operationId: ListCredentials
      summary: List Credentials for an Identity
      description: '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.'
      security:
      - BearerAuth:
        - credentials:read
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      - $ref: '#/components/parameters/realm_id'
      - $ref: '#/components/parameters/identity_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 `credentials` and `total_size`. `credentials` will be set to an array of credential objects, each of which contains the standard credential 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/ListCredentialsResponse'
              examples:
                Success:
                  value:
                    credentials:
                    - id: 81490afab171aef0
                      identity_id: e85de356dc78843a
                      realm_id: 7df92e4a38ba0993
                      tenant_id: 0001b42d80372976
                      state: ACTIVE
                      csr_type: JWT
                      jwk_json: '{"crv":"P-256","kty":"EC","x":"2MRhz05PJPq3BUfB18AT3HqgWEkI3VpWUg1MWi8rz1g","y":"YtvLYwGEqYQaoDVok2fVziJT4fu7DFPz3hy96FTAelQ"}'
                      jwk_thumbprint: UW-uVNL0mP1vcLjHrTBxibNgCEe_PD0HIsE3FrbYjPA=
                      create_time: '2022-03-14T03:42:52.905657Z'
                      update_time: '2022-06-14T05:55:23.823187Z'
                    total_size: 1
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid Parameters:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms/get/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'
        '500':
          description: Internal.
          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}/identities/{identity_id}/credentials/{credential_id}:
    get:
      tags:
      - Credentials
      operationId: GetCredential
      summary: Retrieve an Existing Credential
      description: To retrieve an existing credential, send a GET request to `/v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credentials/$CREDENTIAL_ID`.
      security:
      - BearerAuth:
        - credentials:read
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      - $ref: '#/components/parameters/realm_id'
      - $ref: '#/components/parameters/identity_id'
      - $ref: '#/components/parameters/credential_id'
      responses:
        '200':
          description: 'The response will be a JSON object containing the standard attributes associated with a credential.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
              examples:
                Success:
                  value:
                    id: 81490afab171aef0
                    identity_id: e85de356dc78843a
                    realm_id: 7df92e4a38ba0993
                    tenant_id: 0001b42d80372976
                    state: ACTIVE
                    csr_type: JWT
                    jwk_json: '{"crv":"P-256","kty":"EC","x":"2MRhz05PJPq3BUfB18AT3HqgWEkI3VpWUg1MWi8rz1g","y":"YtvLYwGEqYQaoDVok2fVziJT4fu7DFPz3hy96FTAelQ"}'
                    jwk_thumbprint: UW-uVNL0mP1vcLjHrTBxibNgCEe_PD0HIsE3FrbYjPA=
                    create_time: '2022-03-14T03:42:52.905657Z'
                    update_time: '2022-06-14T05:55:23.823187Z'
        '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:
                Credential Not Found:
                  value:
                    code: not_found
                    message: credential not found
                    details:
                    - type: ResourceInfo
                      resource_type: Credential
                      id: 51c3c2d2907d6b40
                      description: credential not found
        '500':
          description: Internal.
          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}/identities/{identity_id}/credentials/{credential_id}:revoke:
    post:
      tags:
      - Credentials
      operationId: RevokeCredential
      summary: Revoke a Credential
      description: To revoke a credential, send a POST request to `/v1/tenants/$TENANT_ID/realms/$REALM_ID/identities/$IDENTITY_ID/credentials/$CREDENTIAL_ID:revoke`.
      security:
      - BearerAuth:
        - credentials:revoke
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      - $ref: '#/components/parameters/realm_id'
      - $ref: '#/components/parameters/identity_id'
      - $ref: '#/components/parameters/credential_id'
      responses:
        '200':
          description: 'The response will be a JSON object containing the standard attributes associated with a credential.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
              examples:
                Success:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1identities~1%7Bidentity_id%7D~1credentials~1%7Bcredential_id%7D/get/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:
                Credential Not Found:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1identities~1%7Bidentity_id%7D~1credentials~1%7Bcredential_id%7D/get/responses/404/content/application~1json/examples/Credential%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'
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
    credential_id:
      name: credential_id
      in: path
      description: A unique identifier for a credential.
      required: true
      schema:
        type: string
        example: b5a31610800dda18
    identity_id:
      name: identity_id
      in: path
      description: A unique identifier for an identity.
      required: true
      schema:
        type: string
        example: e372db224c06e850
    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
    Credential:
      title: Credential
      description: 'A credential is also known as a passkey. This is the public-private key pair that belongs to an identity.

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

            '
          readOnly: true
          example: f3e87aa26a696372
        identity_id:
          type: string
          description: 'A unique identifier for the credential''s identity. This is automatically set on creation. This field is immutable and read-only.

            '
          readOnly: true
          example: 4a2719e73d6d972d
        realm_id:
          type: string
          description: 'A unique identifier for the credential''s realm. This is automatically set on creation. This field is immutable and read-only.

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

            '
          readOnly: true
          example: f1a7309c1e3d1e85
        state:
          type: string
          enum:
          - ACTIVE
          - REVOKED
          description: 'A string representing the current state of the credential.


            The value `ACTIVE` indicates that the credential can be used to

            authenticate with Beyond Identity.


            The value `REVOKED` indicates that the credential has been revoked and

            cannot be used to authenticate with Beyond Identity.

            '
          readOnly: true
          example: ACTIVE
        csr_type:
          type: string
          enum:
          - JWT
          - WEBAUTHN
          - FIDO2
          description: 'A string representing the type of certificate signing request that

            created this credential.


            The value `JWT` indicates that the CSR was delivered in the form of a JWT.


            The value `WEBAUTHN` indicates that the CSR was delivered in the form of a

            WebAuthn attestation response.


            `FIDO2` indicates that `raw` contains a FIDO2 WebAuthn (Level 2 at the

            time of writing) attestation response object.

            '
          readOnly: true
          example: JWT
        jwk_json:
          type: string
          description: 'The public key of the Credential in JWK format, as specified by RFC-7517. This field is immutable and read-only.

            '
          readOnly: true
          example: '{"crv":"P-256","kty":"EC","x":"2MRhz05PJPq3BUfB18AT3HqgWEkI3VpWUg1MWi8rz1g","y":"YtvLYwGEqYQaoDVok2fVziJT4fu7DFPz3hy96FTAelQ"}'
        jwk_thumbprint:
          type: string
          description: 'The base64 URL encoding of the JWK thumbprint of the public key, as specified by RFC-7638. This field is immutable and read-only.

            '
          readOnly: true
          example: UW-uVNL0mP1vcLjHrTBxibNgCEe_PD0HIsE3FrbYjPA=
        create_time:
          type: string
          format: date-time
          description: 'A time value given in ISO8601 combined date and time format that represents when the credential was created. This is automatically generated on creation. This field is read-only.

            '
          readOnly: true
          example: '2022-05-12T20:29:47.636497Z'
        update_time:
          type: string
          format: date-time
          description: 'A time value given in ISO8601 combined date and time format that represents when the credential was last updated. This is automatically updated when the credential is updated. This field is read-only.

            '
          readOnly: true
          example: '2022-05-12T20:29:47.636497Z'
    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
    ListCredentialsResponse:
      title: List Credentials Response
      description: Response for ListCredentials.
      type: object
      properties:
        credentials:
          type: array
          items:
            $ref: '#/components/schemas/Credential'
          maxItems: 200
          description: 'An unordered array of credentials 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:
      - credentials
      - total_size
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'See the [Authentication](#section/Authentication) section for details.

        '