Authorization API

The BindID Service exposes an HTTP OIDC /authorize endpoint defined by the OIDC standard, which can be used to initiate BindID authentication flows. If the authentication succeeds, a redirect is issued to the requested redirect URI, which will include the authentication result. The BindID SDKs can also be used to build the OIDC authorization request and process the authentication response.

HTTP Request

The /authorize endpoint supports GET requests. It is available on the BindID Service at:

https://<host-name>/authorize

where <host-name> has the following value depending on the environment:

Sandbox: signin.bindid-sandbox.io
Production: signin.identity.security
Production EU: signin.eu.identity.security

Request Parameters

The /authorize request supports both url-encoded parameters or an encrypted request object JWT (using a key obtained via the JWKS API). The following parameters are supported, where all parameters (except those prefixed with bindid) are defined as per the OIDC standard:

Field Name	Description	Type
`client_id`	Required. Client ID issued to the client via the BindID Admin Portal. Equivalent to the `clientId` parameter of the `initialize()` SDK call.	`String`
`redirect_uri`	Required. URI to which the user-agent will be redirected when the authentication process is completed (which must correspond to one of the allowed URIs configured in the BindID Admin Portal). Equivalent to the `redirectUri` parameter of the `authenticate()` SDK call.	`String`
`response_type`	Required. Should be set to `code` (only Authorization Code Flow is supported).	`String`
`response_mode`	Optional. Only `query` is supported (default for the Authorization Code Flow). As such, it is not recommended to pass this parameter, as per the OIDC standard.	`String`
`scope`	Required. Set of scopes that will include additional info in the ID token claims (if this info is already available, for example, from a data verification you once requested). If needed, users will be asked for the relevant consent. Available options: `openid` (mandatory), `bindid_network_info`, `phone` and `email`. Equivalent to the `scope` parameter of the `authenticate()` SDK call.	`String`
`nonce`	Recommended. Nonce value for the authorization request. This value will be included in the ID token. Equivalent to the `nonce` parameter of the `authenticate()` SDK call.	`String`
`state`	Recommended. State value for the authorization request, which will be included in the authorization response sent to the client. Equivalent to the `state` parameter of the `authenticate()` SDK call.	`String`
`display`	Optional. Only `page` is supported.	`String`
`prompt`	Optional. Only `login` is supported.	`String`
`max_age`	Optional. Ignored by BindID.	`String`
`acr_values`	Optional. Requested ACR values, specified as a space-separated string. Available options: `ts.bindid.iac.email` (to require a verified email address) and `ts.bindid.iac.phone_number` (to require a verified phone number). Equivalent to the `verifications` parameter of the `authenticate()` SDK call.	`String`
`claims`	Optional. Object containing claims to return in the ID token (only `id_token` is supported). The structure is per the OIDC Standard. These claims are supported: `bindid_psd2_transaction` - for transaction signing requests (requesting this claim is equivalent to the `signTransaction()` SDK call); `bindid_approval` - for creating custom approval request flows (requesting this claim is equivalent to the `invokeApproval()` Web SDK call).	claims
`id_token_hint`	Optional. Ignored by BindID.	`String`
`login_hint`	Optional. Hint for the user’s login identifier (e.g., email). Currently, only email is supported. The email can either be specified directly, or in the following format: `email:[emailAddress]`, where [emailAddress] is the user's email.	`String`
`ui_locales`	Optional. Preferred languages for the user interface, specified as a space-separated list of language tag values [RFC5646], ordered by preference.	`String`
`code_challenge`	Optional. Code challenge required for a PKCE flow.	`String`
`code_challenge_method`	Optional. Code verifier transformation method, which is required for a PKCE flow. Only `S256` is currently supported.	`String`
`bindid_custom_message`	Optional. Custom message to present on the consent screens, which provides authentication context details. Equivalent to the `customMessage` parameter of the `authenticate()` SDK call.	`String`
`bindid_aux_link`	Optional. A URL target for the custom option link presented on the Computer-to-Mobile Options screen, whose prefix must correspond to the one configured in the BindID Admin Portal, and which must begin with `https://` and end with `/`. If not provided, no link will be displayed. Equivalent to `url` of `otherLoginOptions` parameter of the `authenticate()` SDK call.	`String`
`bindid_aux_link_title`	Optional. Title for the custom option link presented on the Computer-to-Mobile Options screen. Equivalent to `title` of `otherLoginOptions` parameter of the `authenticate()` SDK call.	`String`
`bound_to`	Optional. Used to require an authenticating device that was previously confirmed for the specified user (e.g., for step-up authentication). A confirmed device is a device bound to the Client Application for the user (via `/session-feedback` API), as reflected in the ID token by the `ts.bindid.app_bound_cred` ACR value. This parameter should specify the user identifier in the following format: `[identifierType]:[identifierValue]`, where [identifierType] can either be `alias` (user alias) or `sub` (subject of the ID token). Equivalent to `boundTo` parameter of the `authenticate()` SDK call.	`String`

claims Object

Here is the structure of value when requesting any type of claim:

Field	Description	Type
`display_data`	Required. Object containing data displayed to the user as part of the approval request, as described below.	`Object`
`additional_data`	Optional. Additional data about the approval request that is not displayed to the user but returned in the ID token.	`Object`

bindid_psd2_transaction Claim

Here is the structure of the display_data object for value for a bindid_psd2_transaction claim:

Field	Description	Type
`payee`	Required. Requested payment recipient.	`String`
`payment_amount`	Required. Requested payment amount, including the currency symbol (such as $100.50).	`String`
`payment_method`	Required. Requested payment method (such as Acme Card).	`String`

Here is an example of the structure of a bindid_psd2_transaction claims object:

{
   "id_token": {
      "bindid_psd2_transaction": {
         "essential": true,
         "value": {
           "display_data": {
             "payee": "Acme",
             "payment_amount": "$100",
             "payment_method": "Acme Card"
           }
         }
      }
   }
}

bindid_approval Claim

Here is the structure of the display_data object for value for a bindid_approval claim:

Field	Description	Type
`main_attribute`	Optional. Object containing the main attribute of the approval request, which is emphasized in the UI consent screen. It contains these fields: `label` (required, string) and `value` (required, string).	Object
`attributes`	Required. Array of attributes displayed to the user as part of the approval request, used to provide authentication context details. Each array element has these fields: `label` (required, string), `value` (required, string), and `icon` (optional, string, see below). When the `icon` field is not specified, the `Payment` icon is used. The array can contain a maximum of two elements.	Array of objects

icon Field Values

The icon field can contain these values:

Value	Icon
`Payment`
`Locations`
`Contract`
`Email`
`SmartPhone`
`Id`
`Edit`
`Calendar`
`Lock`
`Globe`

Here is an example of the structure of a bindid_approval claims object:

{
    "id_token": {
        "bindid_approval": {
            "essential": true,
            "value": {
                "display_data": {
                    "main_attribute": {
                        "label": "Account name",
                        "value": "ACME Suppliers"
                    },
                    "attributes": [
                        {
                            "label": "Bank name",
                            "value": "Big Bank",
                            "icon": "Contract"
                        },
                        {
                            "label": "Account number",
                            "value": "123456",
                            "icon": "Id"
                        }
                    ]
                }
            }
        }
    }
}

Request Example

https://signin.bindid-sandbox.io/authorize?
client_id=qL4IJvJ1kHwunrLNOGhAAVCMD39EDPWF&redirect_uri=https%3A%2F%2Fyour-rp.example.com&state=demo_state&bindid_aux_link_title=More%20ways%20to%20verify&bindid_aux_link=https%3A%2F%2Fyour-rp.example.com%2Fother_login&bindid_custom_message=Login%20to%20Acme&scope=openid%20email&acr_values=ts.bindid.iac.email&display=page&prompt=login&response_type=code&login_hint=email%3Auser%40email.com&bound_to=alias%3Auser%40email.com

Response Headers

The response includes the following HTTP headers:

Header Name	Description
`Content-Type`	Returns `application/html`

Response Body

The response to a successful /authorize request is an HTTP 200 response with status OK.

Authentication Failures

In addition to OIDC specification (Section 3.1.2.6) error responses, the following BindID error responses may be returned as part of the redirect URI:

Response Code	Description
`unsupported_browser`	Either a mobile authentication was attempted from an unsupported browser or the user failed to open a QR link with a supported browser within 30 seconds during a desktop to mobile authentication flow. For a list of supported browsers, see Platform Support.
`risk_access_restriction`	Authentication was attempted from a blocked location (see Risk & Trust).
`xm_mfca_required`	FIDO2 authentication is required but authentication was attempted from a device without FIDO2 support or the user failed to complete biometric authentication using a previously registered device.
`device_not_bound`	Confirmed device authentication is required (`bound_to`) but authentication was attempted from an unconfirmed device.

Authorization API#

HTTP Request#

Request Parameters#

claims Object#

Request Example#

Response Headers#

Response Body#

Authentication Failures#