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.bindid.io

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 NameDescriptionType
client_idRequired. Client ID issued to the client via the BindID Admin Portal. Equivalent to the clientId parameter of the initialize() SDK call.String
redirect_uriRequired. 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_typeRequired. Should be set to code (only Authorization Code Flow is supported).String
response_modeOptional. 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
scopeRequired. 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
nonceRecommended. 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
stateRecommended. 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
displayOptional. Only page is supported.String
promptOptional. Only login is supported.String
max_ageOptional. Ignored by BindID.String
acr_valuesOptional. 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
claimsOptional. Object containing claims to return in the ID token (only id_token is supported). The structure is per the OIDC Standard. Only the bindid_psd2_transaction claim is supported (required for transaction signing requests), as described below. Requesting this claim is equivalent to the transactionSigningData parameter of the authenticate() SDK call.Object
id_token_hintOptional. Ignored by BindID.String
login_hintOptional. Ignored by BindID.String
ui_localesOptional. Preferred languages for the user interface, specified as a space-separated list of language tag values [RFC5646], ordered by preference.String
code_challengeOptional. Code challenge required for a PKCE flow.String
code_challenge_methodOptional. Code verifier transformation method, which is required for a PKCE flow. Only S256 is currently supported.String
bindid_custom_messageOptional. 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_linkOptional. 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_titleOptional. 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

For the claims parameter, here is the structure of values when requesting the bindid_psd2_transaction claim:

FieldDescriptionType
display_dataRequired. Object containing transaction details to display to the user to approve for transaction signing requests, as described below.Object
additional_dataOptional. Additional data about the transaction that is not displayed to the user but returned in the ID token.Any

For the claims parameter, here is the structure of the display_data object for values for the bindid_psd2_transaction claim:

FieldDescriptionType
payeeRequired. Requested payment recipient.String
payment_amountRequired. Requested payment amount, including the currency symbol (such as $100.50).String
payment_methodRequired. Requested payment method (such as Acme Card).String

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

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

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

Response Headers

The response includes the following HTTP headers:

Header NameDescription
Content-TypeReturns application/html

Response Body

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

Authentication Failures

For error responses returned due to a failed authentication (as part of the redirect URI), see the OIDC specification - Section 3.1.2.6