Token API

The BindID Service exposes an HTTP OIDC /token endpoint defined by the OIDC standard, which can be used to retrieve the ID and access tokens. This endpoint is used to obtain tokens for an Authorization Code Flow (with or without PKCE), a CIBA Flow (using standard polling or ping notifications), and BindID Management APIs. The response to a successful /token request is an HTTP 200 response, with the structure described below.

HTTP Request

The OIDC /token endpoint is available on the BindID Service at:

https://<host-name>/token

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 Headers

The POST request must include the following HTTP headers:

Header Name	Description
`Content-Type`	Should be set to `application/x-www-form-urlencoded`

Request Body

The body for this POST request is a Form Serialization, where the required fields depend on the flow.

Authorization Code Flow

These fields are required for an Authorization Code Flow token request:

Field Name	Description	Type
`client_id`	Required. Client identifier issued to the client that requested the authorization.	`String`
`client_secret`	Required. Client secret provided to the client that requested the authorization.	`String`
`code`	Required. Authorization code returned in the authorization response for an Authorization Code Flow. This corresponds to the code property returned by the BindID SDK `processRedirectResponse()` method.	`String`
`grant_type`	Required. Should be set to `authorization_code`.	`String`
`redirect_uri`	Required. Redirect URI passed in the authorization request for an Authorization Code Flow.	`String`

Authorization Code with PKCE Flow

These fields are required for an Authorization Code Flow with PKCE token request:

Field Name	Description	Type
`client_id`	Required. Client identifier issued to the client that requested the authorization.	`String`
`code`	Required. Authorization code returned in the authorization response for an Authorization Code Flow. This corresponds to the code property returned by the BindID SDK `processRedirectResponse()` method.	`String`
`code_verifier`	Required. Code verifier required for PKCE flows, used to verify the code challenge passed in the authorization request.	`String`
`grant_type`	Required. Should be set to `authorization_code`.	`String`
`redirect_uri`	Required. Redirect URI passed in the authorization request for an Authorization Code Flow.	`String`

CIBA Flow

These fields are required for a CIBA Flow token request:

Field Name	Description	Type
`auth_req_id`	Required. Unique identifier that identifies the authentication request for a CIBA Flow.	`String`
`client_id`	Required. Client identifier issued to the client that requested the authorization.	`String`
`client_secret`	Required. Client secret provided to the client that requested the authorization.	`String`
`grant_type`	Required. Should be set to `urn:openid:params:grant-type:ciba`.	`String`

BindID Management API Authorization

These fields are required to generate a BindID Management API bearer token:

Field Name	Description	Type
`client_id`	Required. BindID API Credentials ID, as created in the BindID Admin Portal.	`String`
`client_secret`	Required. BindID API Secret, as created in the BindID Admin Portal.	`String`
`grant_type`	Required. Should be set to `client_credentials`.	`String`
`scope`	Required. Should be set to `bindid_admin_api`.	`String`

Request Example

Here's an example of a /token request for an Authorization Code Flow:

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: signin.bindid-sandbox.io

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fyour-rp.example.org&client_id=qL4IJvJ1kHwunrLNOGhAAVCMD39EDPWF&client_secret=123

Here's an example of a /token request for a CIBA Flow:

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: signin.bindid-sandbox.io

grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1&client_id=qL4IJvJ1kHwunrLNOGhAAVCMD39EDPWF&client_secret=123

Here's an example of a /token request for a Management API bearer token:

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: signin.bindid-sandbox.io

grant_type=client_credentials%3Aclient_id=76a199bf.management_api_app.tid_4142b590.bindid.io%3Aclient_secret=d32f7ab9-448c-4e48-ace8-c1598b654be0%3Ascope=bindid_admin_api

Response Headers

The POST response includes the following HTTP headers:

Header Name	Description
`Content-Type`	Returns `application/json`
`Cache-Control`	Returns `no-store`
`Pragma`	Returns `no-cache`

Response Body

The JSON object in the body has the following structure:

Field Name	Description	Type
`access_token`	An opaque access token.	`String`
`token_type`	Audience of the token. Returned as `Bearer`.	`String`
`expires_in`	Expiration time of the access token in seconds.	`Number`
`id_token`	OIDC ID token, containing the claims described below.	`String`
`scope`	Scope of the access token.	`String`

Note: The status of authentication links sent to end users via CIBA flows are indicated as an authorization_pending error (see failure response).

ID Token Claims

The ID token contains a set of claims that are always included and additional claims that are returned based on the context:

Standard Claims
BindID Info Claims
BindID Transaction Info Claims
BindID Custom Approval Claims
Feedback Claims
Email Scope Claims
Phone Scope Claims
BindID Network Scope Claims

Standard Claims

The following claims are always included in ID tokens minted by BindID, as per the OIDC standard:

Claim ID	Description	Type
`iss`	URL identifying the BindID service, according to the environment: sandbox is `https://signin.bindid-sandbox.io`, production is `https://signin.identity.security`, and production EU is `https://signin.eu.identity.security`.	`String`
`sub`	External User ID (ExtUID) assigned to the authenticated user, which is shared across all service providers. The ExtUID is structured as a UUID.	`String`
`aud`	Client ID of the client associated with the token request.	`String`
`exp`	Expiration time of the ID Token, as a unix-epoch encoded timestamp in seconds.	`Number`
`iat`	Generation time of the ID Token, as a unix-epoch encoded timestamp in seconds.	`Number`
`auth_time`	Time when authentication completed, as a unix-epoch encoded timestamp in seconds.	`Number`
`nonce`	Nonce value provided to the authentication request.	`String`
`acr`	ACR values computed for this authentication process, formatted as a space-delimited string.	`String`
`amr`	AMR values computed for this authentication process.	`Array of Strings`

The following ACR values may be returned in the ID token after a successful authentication:

ACR	Description
`ts.bindid.app_bound_cred`	Authenticator used is bound to Client Application authentication (based on a previous session feedback request for this Client Application).
`ts.bindid.iac.email`	Authentication used an authenticator that is associated with a Verified Email Address.
`ts.bindid.iac.phone_number`	Authentication used an authenticator that is associated with a Verified Mobile Phone.

The following AMR values may be returned in the ID token after a successful authentication:

AMR	Description
`ts.bind_id.ama`	Mobile authentication was used in the authentication process. If included, the other AMR values will correspond to the mobile authentication.
`ts.bind_id.mfca`	Multi-factor cryptographic authenticator (e.g., FIDO2) was used.
`ts.bind_id.email_otp`	Email verification code (OTP) was used (e.g., for new user registration). For a known device, this was the fallback authentication method since no multi-factor cryptographic authenticator (e.g., FIDO2) was available.
`ts.bind_id.email_magic_link`	Email verification link was used. This was the fallback authentication method since no multi-factor cryptographic authenticator (e.g., FIDO2) was available.
`ts.bind_id.device`	Bound or fingerprinted device was used (e.g., mobile approval). This was the fallback authentication method since no multi-factor cryptographic authenticator (e.g., FIDO2) was available.

For example:

{
     "iss": "https://signin.bindid-sandbox.io",
     "sub": "123e4567-e89b-12d3-a456-426652340000",
     "aud": "qL4IJvJ1kHwunrLNOGhAAVCMD39EDPWF",
     "exp": 1605267102,
     "iat": 1605180702,
     "auth_time": 1605180698,
     "nonce": "n-077-RsA2Kh",
     "acr":"ts.bindid.iac.email ts.bindid.iac.phone_number",
     "amr": ["ts.bind_id.ama", "ts.bind_id.mfca"],
     ...
}

BindID Info Claims

The following claim encapsulates BindID-specific information based on the context of the current login, and is always returned.

Claim ID	Description	Type
`bindid_info`	Object containing BindID-specific information related to the devices and client applications associated with the current authentication.	`Object`

Structure of each bindid_info object:

Field	Description	Type
`originating_device`	Device information object containing information corresponding to the device that initiated the login.	`Object`
`authenticating_device`	Device information object containing information corresponding to the device used to authenticate.	`Object`
`capp_last_login`	Time of the previous login to the Client Application by the BindID user, as a unix-epoch encoded timestamp in seconds.	`Number`
`capp_last_login_from_authenticating_device`	Time of the previous login to the Client Application by the BindID user from the current authenticating device, as a unix-epoch encoded timestamp in seconds.	`Number`
`capp_first_login`	Time of the first login to the Client Application by the BindID user, as a unix-epoch encoded timestamp in seconds.	`Number`
`capp_first_confirmed_login`	Time of the first login to the Client Application by the BindID user, for which a `/session-feedback` request was sent to confirm the login. This is only returned upon the next login after it was confirmed for this Client Application. The time is formatted as a unix-epoch encoded timestamp in seconds.	`Number`
`capp_first_login_from_authenticating_device`	Time of the first login to the Client Application by the BindID user from the current authenticating device, as a unix-epoch encoded timestamp in seconds.	`Number`

Structure of each device info object (e.g., in the originating_device claim):

Field	Description	Type
`device_name`	Device manufacturer and model.	`String`
`os_type`	OS type of the device.	`String`
`os_version`	OS version of the device.	`String`
`browser_type`	Type of browser used, if relevant.	`String`
`browser_version`	Version of browser used, if relevant.	`String`

For example:

{
   ...
   "bindid_info": {
      "capp_first_login_from_authenticating_device": 1605180500,
      "authenticating_device": {
         "device_name": "Samsung Galaxy A30s"
         "browser_type": "Chrome",
         "os_type": "Android",
         "os_version": "10",
         "browser_version": "97.0.4692.98"
      },
      "capp_last_login_from_authenticating_device": 1605180574,
      "capp_last_login": 1605180577,
      "capp_first_login": 1605180504,
      "capp_first_confirmed_login": 1605180577,
      "originating_device": {
         "device_name": "Apple Macintosh"
         "browser_type": "Chrome",
         "os_type": "Mac OS",
         "os_version": "10.15.7",
         "browser_version": "86.0.4240.183"
      }
   }
   ...
}

BindID Transaction Info Claims

The following claim is added to the ID token for transaction signing requests (such as requests invoked using the signTransaction() SDK call):

Claim ID	Description	Type
`bindid_psd2_transaction`	Object containing transaction details related to the transaction signing request.	`Object`

Structure of the bindid_psd2_transaction claim:

Field	Description	Type
`additional_data`	Additional data about the transaction that was provided as part of the transaction signing request.	`Any`
`display_data`	Object representing transaction details that were displayed to the user in order to consent to the transaction request. The transaction details were provided as part of the transaction signing request.	`Object`

Structure of the display_data object:

Field	Description	Type
`payee`	The recipient of the funds from this transaction.	`String`
`payment_amount`	The transaction amount. This field can include the transaction's currency symbol or code.	`String`
`payment_method`	The payment method that is used to perform the payment.	`String`

For example:

{
   ...
   "bindid_psd2_transaction": {
      "display_data": {
         "payee": "Acme",
         "payment_amount": "$100.00",
         "payment_method": "Acme Card"
      }
   }
   ...
}

BindID Custom Approval Claims

The following claim is added to the ID token for custom BindID approval requests invoked via the Authorization API or the Web SDK invokeApproval() call:

Claim ID	Description	Type
`bindid_approval`	Object containing details related to the custom approval request.	`Object`

Structure of the bindid_approval claim:

Field	Description	Type
`additional_data`	Additional data about the approval that was provided as part of the custom approval request.	`Object`
`display_data`	Object representing approval details that were displayed to the user in order to consent to the request. The approval details were provided as part of the custom approval request.	`Object`

Structure of the display_data object:

Field	Description	Type
`main_attribute`	Object containing the main attribute of the approval request, which is displayed to the user as part of the custom approval request. It contains the defined `label` and `value` fields.	`Object`
`attributes`	Array of attributes displayed to the user as part of the approval request. It contains the defined `label`, `value`, and `icon` fields.	`Array of objects`

For example:

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

Feedback Claims

The following claims are included based on the Service Provider feedback, in addition to the ts.bindid.app_bound_cred ACR value described above.

Claim ID	Description	Type
`bindid_alias`	Alias for this user for the Client Application, provided by the Service Provider via `/session-feedback` API.	`String`

For example:

{
   ...
   "bindid_alias": "username@domain"
   ...
}

Email Scope Claims

The following claims are included in the ID token if the email scope is passed in the authentication request, and this info is available for the user:

Claim ID	Description	Type
`email`	Email address verified for this user.	`String`
`email_verified`	True if the email address was verified (e.g., by email OTP); false otherwise.	`Boolean`
`email_last_update`	Time frame in which the email address was last verified (counted per UTC timezone). Options are: `Last 24 hours`, `Last 7 days`, `Last 28 days`, and `Over 28 days ago`.	`String`

For example:

{
     ...
     "email": "user@acme.com",
     "email_verified": true,
     "email_last_update": "Over 28 days ago"
     ...
}

Phone Claims

The following claims are included in the ID token if the phone scope is passed in the authentication request, and this info is available for the user:

Claim ID	Description	Type
`phone_number`	Mobile phone number verified for this user.	`String`
`phone_number_verified`	True if the mobile phone number was verified (e.g., by SMS OTP); false otherwise.	`Boolean`
`phone_number_last_update`	Time frame in which the mobile phone number was last verified (counted per UTC timezone). Options are: `Last 24 hours`, `Last 7 days`, `Last 28 days`, and `Over 28 days ago`.	`String`

For example:

{     
     ...
     "phone_number": "+12125556789",
     "phone_number_verified": true,
     "phone_number_last_update": "Over 28 days ago"
     ...
 }

BindID Network Scope Claims

The following claims are included in the ID token if the bindid_network_info scope is passed in the authentication request:

Claim ID	Description	Type
`bindid_network_info`	Object containing BindID-specific information related to the user and device collected in the context of all service providers integrated with BindID.	`Object`

Structure of each bindid_network_info object:

Field	Description	Type
`device_count`	Number of devices registered for this BindID user.	`Number`
`user_registration_time`	Time frame in which the user registered to BindID (counted per UTC timezone). Options are: `Last 24 hours`, `Last 7 days`, `Last 28 days`, and `Over 28 days ago`.	`String`
`authenticating_device_registration_time`	Time frame in which the authenticating device was registered to BindID (counted per UTC timezone). Options are: `Last 24 hours`, `Last 7 days`, `Last 28 days`, and `Over 28 days ago`. This device corresponds to the mobile device for appless mobile authentication; otherwise, it corresponds to the computer.	`String`
`confirmed_capp_count`	Count of distinct Client Applications that have confirmed this BindID user.	`Number`
`user_last_seen`	Time frame in which the previous BindID flow was completed for the user, across all service providers (counted per UTC timezone). Options are: `Last 24 hours`, `Last 7 days`, `Last 28 days`, and `Over 28 days ago`.	`String`
`authenticating_device_last_seen`	Time frame in which the previous BindID flow was completed for the user using the current authenticating device across all service providers (counted per UTC timezone). Options are: `Last 24 hours`, `Last 7 days`, `Last 28 days`, and `Over 28 days ago`.	`String`

For example:

{
   ...
   "bindid_network_info": {
      "user_registration_time": "Over 28 days ago",
      "authenticating_device_registration_time": "Over 28 days ago",
      "authenticating_device_last_seen": "Over 28 days ago",
      "user_last_seen": "Over 28 days ago",
      "confirmed_capp_count": 1,
      "device_count": 2
   }
   ...
}

Response Example

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "hjg2khf236ghf",
    "token_type": "Bearer",
    "expires_in": 3600,
    "id_token": "aof ... dfhsf.ksd ... KJhsKJD.lkasjd ... hnsdc"
}

Here’s a complete example of the ID token claim structure:

{
     "iss": "https://signin.identity.security",
     "sub": "123e4567-e89b-12d3-a456-426652340000",
     "aud": "qL4IJvJ1kHwunrLNOGhAAVCMD39EDPWF",
     "exp": 1605267102,
     "iat": 1605180702,
     "auth_time": 1605180698,
     "nonce": "n-077-RsA2Kh",
     "acr": "ts.bindid.iac.email ts.bindid.iac.phone_number",
     "amr": ["ts.bind_id.ama", "ts.bind_id.mfca"],
     "bindid_alias": "username@domain",
     "email": "user@acme.com",
     "email_verified": true,
     "email_last_update": "Over 28 days ago",
     "phone_number": "+12125556789",
     "phone_number_verified": true,
     "phone_number_last_update": "Over 28 days ago",
     "bindid_info": {
        "capp_first_login_from_authenticating_device": 1605180500,
        "authenticating_device": {
           "device_name": "Samsung Galaxy A30s"
           "browser_type": "Chrome",
           "os_type": "Android",
           "os_version": "10",
           "browser_version": "97.0.4692.98"
        },
        "capp_last_login_from_authenticating_device": 1605180574,
        "capp_last_login": 1605180577,
        "capp_first_login": 1605180504,
        "capp_first_confirmed_login": 1605180577,
        "originating_device": {
           "device_name": "Apple Macintosh"
           "browser_type": "Chrome",
           "os_type": "Mac OS",
           "os_version": "10.15.7",
           "browser_version": "86.0.4240.183"
        }
     },
      "bindid_network_info": {
        "user_registration_time": "Over 28 days ago",
        "authenticating_device_registration_time": "Over 28 days ago",
        "authenticating_device_last_seen": "Over 28 days ago",
        "user_last_seen": "Over 28 days ago",
        "confirmed_capp_count": 1,
        "device_count": 2
   }
}

Failures

The response to an invalid or unauthorized /token request is an HTTP 401 response, as described below. For a CIBA Flow, these applicative errors may also be returned in an HTTP 200 response (such as an authorization_pending error when polling).

Response Headers

The POST response includes the following HTTP headers:

Header Name	Description
`Content-Type`	Returns `application/json`
`Cache-Control`	Returns `no-store`
`Pragma`	Returns `no-cache`

Response Body

The JSON object in the body has the following structure:

Field Name	Description	Type
`error`	Single ASCII error code—corresponding to the standard OAuth error codes, or applicative errors.	`String`
`status`	Returned in pending CIBA requests: `link_sent` - the authentication link has been sent to the user; `link_opened` - the user has opened the authentication link.	`String`

Response Examples

Invalid request error:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
     "error": "invalid_request"
}

Incomplete CIBA flow response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "error": "authorization_pending",
    "status": "link_sent"
}

Token API#

HTTP Request#

Request Headers#

Request Body#

Authorization Code Flow#

Authorization Code with PKCE Flow#

CIBA Flow#

BindID Management API Authorization#

Request Example#

Response Headers#

Response Body#

ID Token Claims#

Standard Claims#

BindID Info Claims#

BindID Transaction Info Claims#

BindID Custom Approval Claims#

Feedback Claims#

Email Scope Claims#

Phone Claims#

BindID Network Scope Claims#

Response Example#

Failures#

Response Headers#

Response Body#

Response Examples#

Token API

HTTP Request

Request Headers

Request Body

Authorization Code Flow

Authorization Code with PKCE Flow

CIBA Flow

BindID Management API Authorization

Request Example

Response Headers

Response Body

ID Token Claims

Standard Claims

BindID Info Claims

BindID Transaction Info Claims

BindID Custom Approval Claims

Feedback Claims

Email Scope Claims

Phone Claims

BindID Network Scope Claims

Response Example

Failures

Response Headers

Response Body

Response Examples