openapi: 3.0.1
info:
  title: Beyond Identity Secure Access Applications Themes API
  version: 1.7.0
  contact:
    email: support@beyondidentity.com
  description: "# Introduction\n\n**NOTE:** To determine if you are accessing the Secure Access Platform, check the URL of your Admin Console.\nIf it looks like one of the following, you are using the Secure Access Platform:\n- `https://console.beyondidentity.com` (Localized to your region)\n- `https://console-us.beyondidentity.com` (US region)\n- `https://console-eu.beyondidentity.com` (EU region)\n- `https://console.us1.beyondidentity-gov.com` (US FedRAMP)\n\nIf your Admin Console URL does not look like one of the above, you are using the Secure Workforce Platform. Please refer to the [Secure Workforce API documentation](https://docs.beyondidentity.com/api/v0). <br /><br />\n\nThe Beyond Identity Secure Access API defines methods for managing resources in the Beyond Identity Secure Access platform.<br /><br />\n\nAll of the functionality available in the Beyond Identity Admin Console is\nalso available through the API. <br /><br />\n\nThis API is currently in the early-access stage and is under active\ndevelopment. Feedback and suggestions are encouraged and should be directed\nto the\n[Beyond Identity Developer Slack Channel](https://join.slack.com/t/byndid/shared_invite/zt-1anns8n83-NQX4JvW7coi9dksADxgeBQ).\n\n# Base API URLs\n\nThe base API URLs is determined by the region your tenant is hosted in OR if you are a FedRAMP customer. <br><br>\n\n### US Region\n\nIf you are a US region customer, your base API URLs will be:\n- `https://api-us.beyondidentity.com`\n- `https://auth-us.beyondidentity.com`\n\n### EU Region\n\nIf you are a EU region customer, your base API URLs will be:\n- `https://api-eu.beyondidentity.com`\n- `https://auth-eu.beyondidentity.com`\n\n### US FedRAMP\n\n**NOTE**: The FedRAMP version of Secure Access is released approximately *two weeks* after the commercial version, so some API endpoints may not be available immediately. <br><br>\n\nIf you are a FedRAMP customer in the US region, your base API URLs will be:\n- `https://api.us1.beyondidentity-gov.com`\n- `https://auth.us1.beyondidentity-gov.com`\n\nFor all the examples in this document, we will use the US region API base URL. You can always replace `https://api-us.beyondidentity.com`\nand `https://auth-us.beyondidentity.com` in the examples to use the proper base URL for your tenant.\n\n# Authentication\n\nAll Beyond Identity API endpoints require authentication using an access\ntoken. The access token is generated through OAuth 2.0 or OIDC, using the\nauthorization code flow or the client credentials flow. <br /><br />\n\nThe 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\". <br /><br />\n\nAlternatively, an access token may also be generated directly via the API by\nrequesting a token for the \"Beyond Identity Management API\" Application. <br><br>\n\n```\ncurl https://auth-us.beyondidentity.com/v1/tenants/$TENANT_ID/realms/$REALM_ID/applications/$APPLICATION_ID/token \\\n  -X POST \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\" --basic \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"grant_type=client_credentials&scope=$SCOPES\"\n```\n\nThis will work for any application that you have configured to provide\naccess to the Beyond Identity Management API Resource Server. The \"Beyond\nIdentity Management API\" application is provided by default as part of the\ntenant onboarding process.\n\nThe access token must be provided in the `Authorization` header of the\nAPI request. <br><br>\n\n```\ncurl https://api-us.beyondidentity.com/v1/... \\\n  -X $HTTP_METHOD -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Requests and Responses\n\nTo interact with the Beyond Identity API, all requests should be made over\nHTTPS. <br /><br />\n\nThe Beyond Identity API is generally structured as a resource-oriented API.\nResources are represented as JSON objects and are used as both inputs to\nand outputs from API methods. <br /><br />\n\nResource fields may be described as read-only and immutable. A read-only\nfield is only provided on the response. An immutable field is only assigned\nonce and may not be changed after. For example, system-generated IDs are\ndescribed as both read-only and immutable. <br /><br />\n\nTo create a new resource, requests should use the `POST` method. Create\nrequests include all of the necessary attributes to create a new resource.\nCreate operations return the created resource in the response. <br /><br />\n\nTo retrieve a single resource or a collection of resources, requests should\nuse the `GET` method. When retrieving a collection of resources, the\nresponse will include an array of JSON objects keyed on the plural name of\nthe requested resource. <br /><br />\n\nTo update an resource, requests should use the `PATCH` method. Update\noperations support partial updating so requests may specify only the\nattributes which should be updated. Update operations return the updated\nresource in the response. <br /><br />\n\nTo delete a resource, requests should use the `DELETE` method. Note that\ndelete operations return an empty response instead of returning the\nresource in the response. <br /><br />\n\n### Example Response for a Realm\n\n```\n{\n  \"id\": \"a448fe493e02fa9f\",\n  \"tenant_id\": \"000168dc50bdce49\",\n  \"display_name\": \"Test Realm\",\n  \"create_time\": \"2022-06-22T21:46:08.930278Z\",\n  \"update_time\": \"2022-06-22T21:46:08.930278Z\"\n}\n```\n\n### Example Response for a Collection of Realms\n\n```\n{\n  \"realms\": [\n    {\n      \"id\": \"a448fe493e02fa9f\",\n      \"tenant_id\": \"000168dc50bdce49\",\n      \"display_name\": \"Test Realm\",\n      \"create_time\": \"2022-06-22T21:46:08.930278Z\",\n      \"update_time\": \"2022-06-22T21:46:08.930278Z\"\n    }\n  ],\n  \"total_size\": 1\n}\n```\n\n## HTTP Statuses\n\nThe API returns standard HTTP statuses and error codes.\n\nStatuses in the 200 range indicate that the request was successfully\nfulfilled and there were no errors. <br><br>\n\nStatuses in the 400 range indicate that there was an issue with the request\nthat may be addressed by the client. For example, client errors may\nindicate that the request was missing proper authorization or that the\nrequest was malformed. <br><br>\n\nStatuses in the 500 range indicate that the server encountered an internal\nissue and was unable to fulfill the request. <br><br>\n\nAll error responses include a JSON object with a `code` field and a\n`message` field. `code` contains a human-readable name for the HTTP status\ncode and `message` contains a high-level description of the error. The\nerror object may also contain additional error details which may be used by\nthe client to determine the exact cause of the error. Refer to each API\nmethod's examples to determine the specific error detail types supported\nfor that method. <br><br>\n\n### Invalid Access Token Example\n\nIf the provided access token is invalid, you will receive a 401 error.\nThis error indicates that the token is not recognized and was not generated\nby Beyond Identity. <br><br>\n\n```\nHTTP/1.1 401 Unauthorized\n{\n  \"code\": \"unauthorized\",\n  \"message\": \"unauthorized\"\n}\n```\n\n### Permission Denied Example\n\nIf the provided access token does not have access to the requested resource,\nyou will receive a 403 error. Access tokens are scoped at a minimum to your\ntenant. Any request for resources outside of your tenant will result in this\nerror. <br><br>\n\n```\nHTTP/1.1 403 Forbidden\n{\n  \"code\": \"forbidden\",\n  \"message\": \"forbidden\"\n}\n```\n\n### Missing Resource Example\n\nIf the requested resource does not exist, you will receive a 404 error. The\nspecific API method may return additional details about the missing\nresource. <br><br>\n\n```\nHTTP/1.1 404 Not Found\n{\n  \"code\": \"not_found\",\n  \"message\": \"group not found\"\n  \"details\": [\n    {\n      \"type\": \"ResourceInfo\",\n      \"resource_type\": \"Group\",\n      \"id\": \"4822738be6b7f658\",\n      \"description\": \"group not found\"\n    }\n  ],\n}\n```\n\n### Invalid Parameters Example\n\nIf the request body contains invalid parameters, you will receive a 400\nerror. The specific API method may return additional details about the\ninvalid parameter. <br><br>\n\n```\nHTTP/1.1 400 Bad Request\n{\n  \"code\": \"bad_request\",\n  \"message\": \"invalid parameters\"\n  \"details\": [\n    {\n      \"type\": \"FieldViolations\"\n      \"field_violations\": [\n        {\n          \"description\": \"missing\",\n          \"field\": \"group.display_name\"\n        }\n      ],\n    }\n  ],\n}\n```\n"
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: Themes
  description: '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.

    '
paths:
  /v1/tenants/{tenant_id}/realms/{realm_id}/themes:
    post:
      tags:
      - Themes
      summary: Create a New Theme
      description: '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.

        '
      operationId: CreateTheme
      security:
      - BearerAuth:
        - themes:create
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      - $ref: '#/components/parameters/realm_id'
      requestBody:
        description: Theme to be created.
        content:
          application/json:
            schema:
              title: Create Theme Request
              description: Request for CreateTheme.
              type: object
              properties:
                theme:
                  $ref: '#/components/schemas/Theme'
            examples:
              Create Theme:
                value:
                  theme:
                    email_realm_name: Realm Administrators
                    logo_url_light: https://example.com/logo_url_light.png
                    logo_url_dark: https://example.com/logo_url_dark.png
                    support_url: https://example.com/support
                    button_color: '#4673D3'
                    button_text_color: '#FFFFFF'
      responses:
        '200':
          description: 'The response will be a JSON object containing the standard attributes associated with a theme.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Theme'
              examples:
                Success:
                  value:
                    id: 88ef08fb-c3f9-44e2-b174-fbb239e1dc47
                    tenant_id: f36448f2ff094881
                    realm_id: aa6aabe6989bc4a5
                    email_realm_name: Realm Administrators
                    logo_url_light: https://example.com/logo_url_light.png
                    logo_url_dark: https://example.com/logo_url_dark.png
                    support_url: https://example.com/support
                    create_time: '2022-07-28T18:00:00.000Z'
                    button_color: '#4673D3'
                    button_text_color: '#FFFFFF'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid Parameters:
                  value:
                    code: bad_request
                    message: Bad Request
                    details:
                    - type: FieldViolations
                      field_violations:
                      - field: theme.email_realm_name
                        description: provided email_realm_name must not be 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:
                  value:
                    code: not_found
                    message: realm not found
                    details:
                    - type: ResourceInfo
                      resource_type: Realm
                      id: 19a95130480dfa79
                      description: realm not found
        '409':
          description: Conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Theme Already Exists:
                  value:
                    code: conflict
                    message: theme already exists for this realm
        '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}/themes/active:
    get:
      tags:
      - Themes
      summary: Get the Active Theme
      description: '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.

        '
      operationId: GetActiveTheme
      security:
      - BearerAuth:
        - themes: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 theme.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Theme'
              examples:
                Success:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1themes/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:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1themes/post/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'
  /v1/tenants/{tenant_id}/realms/{realm_id}/themes/{theme_id}:
    get:
      tags:
      - Themes
      summary: Retrive an Existing Theme
      description: 'To retrieve an existing theme, send a GET request to `/v1/tenants/$TENANT_ID/realms/$REALM_ID/themes/$THEME_ID`.

        '
      operationId: GetTheme
      security:
      - BearerAuth:
        - themes:read
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      - $ref: '#/components/parameters/realm_id'
      - $ref: '#/components/parameters/theme_id'
      responses:
        '200':
          description: 'The response will be a JSON object containing the standard attributes associated with a theme.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Theme'
              examples:
                Success:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1themes/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:
                Theme Not Found:
                  value:
                    code: not_found
                    message: theme not found
                    details:
                    - type: ResourceInfo
                      resource_type: Theme
                      id: 72d0af37-a9bb-410c-b8a7-9aa127fd8739
                      description: theme 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:
      - Themes
      summary: Patch a Theme
      description: '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.

        '
      operationId: UpdateTheme
      security:
      - BearerAuth:
        - themes:update
      parameters:
      - $ref: '#/components/parameters/tenant_id'
      - $ref: '#/components/parameters/realm_id'
      - $ref: '#/components/parameters/theme_id'
      requestBody:
        description: Theme to be updated.
        content:
          application/json:
            schema:
              title: Update Theme Request
              description: Request for UpdateTheme.
              type: object
              properties:
                theme:
                  $ref: '#/components/schemas/Theme'
            examples:
              Update Email Realm Name:
                value:
                  theme:
                    email_realm_name: Realm Administrators
      responses:
        '200':
          description: 'The response will be a JSON object containing the standard attributes associated with a theme.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Theme'
              examples:
                Success:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1themes/post/responses/200/content/application~1json/examples/Success'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid Parameters:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1themes/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:
                Theme Not Found:
                  $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1themes~1%7Btheme_id%7D/get/responses/404/content/application~1json/examples/Theme%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:
    realm_id:
      name: realm_id
      in: path
      description: A unique identifier for a realm.
      required: true
      schema:
        type: string
        example: 19a95130480dfa79
    tenant_id:
      name: tenant_id
      in: path
      description: A unique identifier for a tenant.
      required: true
      schema:
        type: string
        example: 000176d94fd7b4d1
    theme_id:
      name: theme_id
      in: path
      description: A unique identifier for a theme.
      required: true
      schema:
        type: string
        example: 88ef08fb-c3f9-44e2-b174-fbb239e1dc47
  schemas:
    Theme:
      title: Theme
      description: '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.

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

            '
          readOnly: true
          example: 88ef08fb-c3f9-44e2-b174-fbb239e1dc47
        tenant_id:
          type: string
          description: 'A unique identifier for the theme''s tenant. This is automatically set on creation. This field is immutable and read-only.

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

            '
          readOnly: true
          example: 7df92e4a38ba0993
        create_time:
          type: string
          format: date-time
          description: 'Timestamp of when the theme was created. This field is immutable and read-only.

            '
          readOnly: true
          example: '2022-07-28T18:00:00.000Z'
        update_time:
          type: string
          format: date-time
          description: 'Timestamp of when the theme was last updated. This field is read-only.

            '
          readOnly: true
          example: '2022-07-30T16:00:00.000Z'
        email_realm_name:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[^{}[\]<>;:?\\/|*^%$#=~`!]*$
          description: Realm name that is used in email templates.
          example: Realm Administrators
        logo_url_light:
          type: string
          description: URL for resolving the logo image for light mode.
          example: https://example.com/logo_url_light.png
        logo_url_dark:
          type: string
          description: URL for resolving the logo image for dark mode.
          example: https://example.com/logo_url_dark.png
        support_url:
          type: string
          format: url
          description: URL for the customer support portal.
          example: https://example.com/support
        button_color:
          type: string
          description: Hexadecimal color code to use for buttons.
          example: '#4673D3'
        button_text_color:
          type: string
          description: Hexadecimal color code to use for button text.
          example: '#FFFFFF'
    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
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'See the [Authentication](#section/Authentication) section for details.

        '