Beyond Identity SSO Configs API

openapi: 3.0.1
info:
  title: Beyond Identity Secure Access Applications SSO Configs 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: SSO Configs
  description: 'An SSO configuration defines how end users interact with supported SSO protocols and related services. Each configuration type represents a protocol or integration (e.g., SAML, WS-Federation, OIDC, SCIM) supported by Beyond Identity. An SSO configuration provides a flexible framework for managing authentication, provisioning, and other integrations. It abstracts application protocols, inbound and outbound provisioning, and supports named integrations. Additionally, it includes features like user or group assignments, visual tiles in the SSO interface, and compatibility with multiple authentication and provisioning standards.  This makes SSO configurations versatile for both authentication and non-authentication use cases.

    '
paths:
  /v1/tenants/{tenant_id}/realms/{realm_id}/sso-configs:
    post:
      summary: Create a new SSO Config.
      description: 'To create a new SSO Config, send a POST request to `/v1/tenants/$TENANT_ID/realms/$REALM_ID/sso-configs`.

        '
      tags:
      - SSO Configs
      operationId: CreateSsoConfig
      parameters:
      - $ref: '#/components/parameters/correlation_id'
      - $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/get/parameters/1'
      - $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/get/parameters/2'
      security:
      - BearerAuth:
        - sso-configs:create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SsoConfigEnvelope'
      responses:
        '200':
          description: The sso config has been created.
          headers:
            x-correlation-id:
              $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/get/responses/200/headers/x-correlation-id'
          content:
            application/json:
              schema:
                description: Represents an SSO config as a response body.
                type: object
                required:
                - id
                - display_name
                - payload
                properties:
                  id:
                    description: A unique identifier for an SSO config. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the realm.
                    type: string
                    format: uuid
                  display_name:
                    description: A human-readable name for the SSO config. This name is used for display purposes.
                    type: string
                  payload:
                    oneOf:
                    - type: object
                      required:
                      - type
                      - login_link
                      properties:
                        type:
                          $ref: '#/components/schemas/SsoConfigType'
                        login_link:
                          type: string
                        icon:
                          type: string
                        is_tile_visible:
                          type: boolean
                        application_tile_id:
                          type: string
                    - type: object
                      required:
                      - type
                      - redirect_uris
                      - application_id
                      - authenticator_config_id
                      - resource_server_id
                      - oidc_configuration
                      - client_id
                      - discover_endpoint
                      properties:
                        type:
                          $ref: '#/components/schemas/SsoConfigType'
                        redirect_uris:
                          type: array
                          items:
                            type: string
                        oidc_configuration:
                          type: object
                          required:
                          - grant_types_supported
                          - introspect_endpoint
                          - issuer
                          - jwks_uri
                          - response_types_supported
                          - token_endpoint
                          - token_endpoint_auth_methods_supported
                          properties:
                            issuer:
                              type: string
                            authorization_endpoint:
                              type: string
                              nullable: true
                            token_endpoint:
                              type: string
                            userinfo_endpoint:
                              type: string
                              nullable: true
                            jwks_uri:
                              type: string
                            response_types_supported:
                              type: array
                              items:
                                type: string
                                enum:
                                - code
                                - id_token
                            token_endpoint_auth_methods_supported:
                              type: array
                              items:
                                $ref: '#/components/schemas/TokenEndpointAuthMethod'
                        client_id:
                          description: The client ID for the idp application.
                          type: string
                        inbound_scim:
                          $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/post/responses/200/content/application~1json/schema/properties/payload/oneOf/8/allOf/0'
                        application_id:
                          type: string
                        authenticator_config_id:
                          type: string
                        resource_server_id:
                          type: string
                        discover_endpoint:
                          $ref: '#/components/schemas/SsoConfigEntraIdExternalAuthMethod/properties/discover_endpoint'
                    - type: object
                      required:
                      - type
                      - redirect_uris
                      - scopes
                      - trusted_origins
                      - confidentiality
                      - pkce
                      - application_id
                      - authenticator_config_id
                      - resource_server_id
                      - oidc_configuration
                      - client_id
                      properties:
                        type:
                          $ref: '#/components/schemas/SsoConfigType'
                        redirect_uris:
                          type: array
                          items:
                            type: string
                        scopes:
                          type: array
                          items:
                            type: string
                        trusted_origins:
                          type: array
                          items:
                            type: string
                        login_link:
                          type: string
                        icon:
                          type: string
                        is_tile_visible:
                          type: boolean
                        confidentiality:
                          $ref: '#/components/schemas/Confidentiality'
                        pkce:
                          $ref: '#/components/schemas/PkceConfig'
                        oidc_configuration:
                          $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/post/responses/200/content/application~1json/schema/properties/payload/oneOf/1/properties/oidc_configuration'
                        client_id:
                          description: The client ID for the idp application.
                          type: string
                        client_secret:
                          description: The client secret to authenticate as the idp application.
                          type: string
                        inbound_scim:
                          $ref: '#/components/schemas/SsoConfigType'
                        application_id:
                          type: string
                        authenticator_config_id:
                          type: string
                        resource_server_id:
                          type: string
                        application_tile_id:
                          type: string
                    - type: object
                      required:
                      - type
                      - client_id
                      - pkce
                      - identifying_claim_name
                      - identity_attribute
                      - authorization_endpoint
                      - token_endpoint
                      - jwks_endpoint
                      - redirect_uri
                      - identity_provider_id
                      properties:
                        type:
                          $ref: '#/components/schemas/SsoConfigType'
                        client_id:
                          description: The client ID for the idp application.
                          type: string
                        client_secret:
                          description: The client secret to authenticate as the idp application.
                          type: string
                        pkce:
                          $ref: '#/components/schemas/PkceConfig'
                        id_token_scopes:
                          type: array
                          items:
                            type: string
                        identifying_claim_name:
                          type: string
                        identity_attribute:
                          $ref: '#/components/schemas/SubjectField'
                        authorization_endpoint:
                          type: string
                          nullable: true
                        token_endpoint:
                          type: string
                        jwks_endpoint:
                          type: string
                        redirect_uri:
                          type: string
                        identity_provider_id:
                          type: string
                    - type: object
                      properties:
                        type:
                          $ref: '#/components/schemas/SsoConfigType'
                        acs_url:
                          type: string
                          description: The Assertion Consumer Service (ACS) URL where the SAML assertions are sent.
                        override_recipient_and_destination:
                          type: boolean
                          description: Flag to override the recipient and destination URLs in the SAML response.
                        recipient_url:
                          type: string
                          description: The recipient URL for the SAML response.
                        destination_url:
                          type: string
                          description: The destination URL for the SAML response.
                        audience_url:
                          type: string
                          description: The URL that identifies the intended audience for the SAML assertion.
                        default_relay_state:
                          type: string
                          description: The default relay state parameter for the SAML response.
                        name_format:
                          $ref: '#/components/schemas/SsoConfigPayload/oneOf/4/properties/name_format'
                          description: The format of the NameID in the SAML assertion.
                        authentication_context:
                          $ref: '#/components/schemas/SsoConfigPayload/oneOf/4/properties/authentication_context'
                          description: The authentication context for the SAML assertion.
                        subject_user_name_attribute:
                          $ref: '#/components/schemas/SsoConfigPayload/oneOf/4/properties/subject_user_name_attribute'
                          description: The attribute used for the subject's username in the SAML assertion.
                        sign_envelope:
                          type: boolean
                          description: Flag indicating whether to sign the SAML envelope.
                        sign_assertions:
                          type: boolean
                          description: Flag indicating whether to sign the SAML assertions.
                        signature_algorithm:
                          $ref: '#/components/schemas/SsoConfigPayload/oneOf/4/properties/signature_algorithm'
                          description: The algorithm used for signing the SAML assertions.
                        digest_algorithm:
                          $ref: '#/components/schemas/SsoConfigPayload/oneOf/4/properties/digest_algorithm'
                          description: The algorithm used for the digest of the SAML assertions.
                        encrypt_assertions:
                          type: boolean
                          description: Flag indicating whether to encrypt the SAML assertions.
                        assertion_validity_duration_seconds:
                          type: integer
                          format: int32
                          description: The duration (in seconds) for which the SAML assertion is valid.
                        assertion_encryption_algorithm:
                          $ref: '#/components/schemas/SsoConfigPayload/oneOf/4/properties/assertion_encryption_algorithm'
                          description: The algorithm used for encrypting the SAML assertions.
                        assertion_key_transport_algorithm:
                          $ref: '#/components/schemas/SsoConfigPayload/oneOf/4/properties/assertion_key_transport_algorithm'
                          description: The algorithm used for key transport when encrypting SAML assertions.
                        assertion_encryption_public_key:
                          type: string
                          description: The public key used for encrypting the SAML assertions.
                        sp_signature_certificates:
                          type: array
                          items:
                            $ref: '#/components/schemas/SsoConfigSamlPartialUpdate/properties/sp_signature_certificates/items'
                          description: The certificates used for signing the SAML assertions.
                        enable_single_log_out:
                          type: boolean
                          description: Flag indicating whether to enable single logout (SLO) functionality.
                        single_log_out_url:
                          type: string
                          description: The URL for single logout (SLO).
                        single_log_out_issuer_url:
                          type: string
                          description: The issuer URL for single logout (SLO).
                        single_log_out_binding:
                          $ref: '#/components/schemas/SsoConfigPayload/oneOf/4/properties/single_log_out_binding'
                          description: The binding method for single logout (SLO) requests.
                        single_logout_sign_request_and_response:
                          type: boolean
                          description: Flag indicating whether to sign the single logout (SLO) requests and responses.
                        validate_signed_requests:
                          type: boolean
                          description: Flag indicating whether to validate signed SAML requests.
                        other_sso_urls:
                          $ref: '#/components/schemas/SsoConfigPayload/oneOf/4/properties/other_sso_urls'
                          description: Other SSO URLs associated with the configuration.
                        additional_user_attributes:
                          description: Additional user attributes to include in the SAML assertions.
                          type: array
                          items:
                            $ref: '#/components/schemas/SsoConfigPayload/oneOf/4/properties/additional_user_attributes'
                        icon:
                          type: string
                          description: The icon associated with the SSO configuration.
                        is_tile_visible:
                          type: boolean
                          description: Flag indicating whether the configuration tile is visible.
                        application_id:
                          type: string
                          description: The application ID associated with the SSO configuration.
                        authenticator_config_id:
                          type: string
                          description: The authenticator configuration ID.
                        application_tile_id:
                          type: string
                          description: The application tile ID.
                        idp_initiated_url:
                          type: string
                          description: The URL for IdP-initiated SSO.
                        sp_initiated_url:
                          type: string
                          description: The URL for SP-initiated SSO.
                        inbound_scim:
                          $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/post/responses/200/content/application~1json/schema/properties/payload/oneOf/8/allOf/0'
                        use_short_url:
                          default: false
                          type: boolean
                          description: Changes the EntityID in the SAML response to a shorter version. This is to support applications with URL restrictions.
                        short_sp_initiated_url:
                          type: string
                          description: This is the shortened URL that will be used to initiate a SAML login from the service provider side. Generated and provided by Beyond Identity. This should only be displayed when `use_short_urls` is true.
                        short_entity_id_url:
                          type: string
                          description: This is the shortened URL that we will use as our issuer inside of a SAML response.
                    - type: object
                      required:
                      - type
                      - client_id
                      - pkce
                      - identifying_claim_name
                      - identity_attribute
                      - okta_domain
                      - authorization_endpoint
                      - token_endpoint
                      - jwks_endpoint
                      - redirect_uri
                      - identity_provider_id
                      properties:
                        type:
                          $ref: '#/components/schemas/SsoConfigType'
                        client_id:
                          description: The client ID for the idp application.
                          type: string
                        client_secret:
                          description: The client secret to authenticate as the idp application.
                          type: string
                        pkce:
                          allOf:
                          - $ref: '#/components/schemas/PkceConfig'
                        id_token_scopes:
                          type: array
                          items:
                            type: string
                        identifying_claim_name:
                          type: string
                        identity_attribute:
                          $ref: '#/components/schemas/SubjectField'
                        okta_domain:
                          type: string
                        authorization_endpoint:
                          type: string
                          nullable: true
                        token_endpoint:
                          type: string
                        jwks_endpoint:
                          type: string
                        redirect_uri:
                          type: string
                        identity_provider_id:
                          type: string
                        inbound_scim:
                          $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/post/responses/200/content/application~1json/schema/properties/payload/oneOf/8/allOf/0'
                    - type: object
                      required:
                      - type
                      - pkce
                      - oidc_configuration
                      - client_id
                      - client_secret
                      - application_id
                      - authenticator_config_id
                      - okta_registration
                      properties:
                        type:
                          $ref: '#/components/schemas/SsoConfigType'
                        pkce:
                          allOf:
                          - $ref: '#/components/schemas/PkceConfig'
                        oidc_configuration:
                          $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/post/responses/200/content/application~1json/schema/properties/payload/oneOf/1/properties/oidc_configuration'
                        client_id:
                          description: The client ID for the idp application.
                          type: string
                        client_secret:
                          description: The client secret to authenticate as the idp application.
                          type: string
                        okta_registration:
                          $ref: '#/components/schemas/SsoConfigOktaBiIdp/properties/okta_registration'
                        inbound_scim:
                          $ref: '#/paths/~1v1~1tenants~1%7Btenant_id%7D~1realms~1%7Brealm_id%7D~1sso-configs/post/responses/200/content/application~1json/schema/properties/payload/oneOf/8/allOf/0'
                        application_id:
                          type: string
                        authenticator_config_id:
                          type: string
                    - type: object
                      required:
                      - type
                      - company_identifier
                      properties:
                        type:
                          $ref: '#/components/schemas/SsoConfigType'
                        company_identifier:
                          type: string
                    - type: object
                      required:
                      - type
                      - application_id
                      - client_id
                      - client_secret
                      - scim_url
                      - token_endpoint
                      properties:
                        type:
            

# --- truncated at 32 KB (165 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/beyond-identity/refs/heads/main/openapi/beyond-identity-sso-configs-api-openapi.yml