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 user tokens for an Authorization Code Flow (with or without PKCE) and a CIBA Flow (using standard polling). 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.bindid.io

Request Headers

The POST request must include the following HTTP headers:

Header NameDescription
Content-TypeShould be set to application/x-www-form-urlencoded

Request Body

The body for this POST request is a Form Serialization, with the following fields:

Field NameDescriptionType
codeAuthorization 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_typeShould be set to authorization_code for an Authorization Code Flow, and set to urn:openid:params:grant-type:ciba for a CIBA Flow.String
redirect_uriRedirect URI passed in the authorization request for an Authorization Code Flow.String
auth_req_idUnique identifier that identifies the authentication request for a CIBA Flow.String
client_idClient identifier issued to the client that requested the authorization.String
client_secretClient secret provided to the client that requested the authorization. This is not required for PKCE flows.String
code_verifierCode verifier required for PKCE flows, used to verify the code challenge passed in the authorization request.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

Response Headers

The POST response includes the following HTTP headers:

Header NameDescription
Content-TypeReturns application/json
Cache-ControlReturns no-store
PragmaReturns no-cache

Response Body

The JSON object in the body has the following structure:

Field NameDescriptionType
access_tokenAn opaque access token.String
token_typeAudience of the token. Returned as Bearer.String
expires_inExpiration time of the access token in seconds.Number
id_tokenOIDC ID token, containing the claims described below.String
scopeScope of the access token.String

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

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

Claim IDDescriptionType
issURL identifying the BindID service, according to the environment: sandbox is https://signin.bindid-sandbox.io and production is https://signin.bindid.ioString
subExternal User ID (ExtUID) assigned to the authenticated user, which is shared across all service providers. The ExtUID is structured as a UUID.String
audClient ID of the client associated with the token request.String
expExpiration time of the ID Token, as a unix-epoch encoded timestamp in seconds.Number
iatGeneration time of the ID Token, as a unix-epoch encoded timestamp in seconds.Number
auth_timeTime when authentication completed, as a unix-epoch encoded timestamp in seconds.Number
nonceNonce value provided to the authentication request.String
acrACR values computed for this authentication process, formatted as a space-delimited string.String
amrAMR values computed for this authentication process.Array of Strings

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

ACRDescription
ts.bindid.app_bound_credAuthenticator used is bound to Client Application authentication (based on a previous session feedback request for this Client Application).
ts.bindid.iac.emailAuthentication used an authenticator that is associated with a Verified Email Address.
ts.bindid.iac.phone_numberAuthentication 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:

AMRDescription
ts.bind_id.amaAppless mobile authentication was used in the authentication process. If included, the other AMR value will correspond to the mobile authenticator used.
ts.bind_id.deviceBound or fingerprinted device was used. No multi-factor authentication process was performed since no suitable authenticator was available.
ts.bind_id.mfcaMulti-factor cryptographic authenticator was used (e.g., FIDO2 authenticator).

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 IDDescriptionType
bindid_infoObject containing BindID-specific information related to the devices and client applications associated with the current authentication.Object

Structure of each bindid_info object:

FieldDescriptionType
originating_deviceDevice information object containing information corresponding to the device that initiated the login.Object
authenticating_deviceDevice information object containing information corresponding to the device used to authenticate.Object
capp_last_loginTime 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_deviceTime 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_loginTime of the first login to the Client Application by the BindID user, as a unix-epoch encoded timestamp in seconds.Number
capp_first_confirmed_loginTime 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_deviceTime 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):

FieldDescriptionType
os_typeOS type of the device.String
os_versionOS version of the device.String
browser_typeType of browser used, if relevant.String
browser_versionVersion of browser used, if relevant.String

For example:

{
...
"bindid_info": {
"capp_first_login_from_authenticating_device": 1605180500,
"authenticating_device": {
"browser_type": "Mobile",
"os_type": "iOS",
"os_version": "14.1",
"browser_version": "Safari"
},
"capp_last_login_from_authenticating_device": 1605180574,
"capp_last_login": 1605180577,
"capp_first_login": 1605180504,
"capp_first_confirmed_login": 1605180577,
"originating_device": {
"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 IDDescriptionType
bindid_psd2_transactionObject containing transaction details related to the transaction signing request.Object

Structure of the bindid_psd2_transaction claim:

FieldDescriptionType
additional_dataAdditional data about the transaction that was provided as part of the transaction signing request.Any
display_dataObject 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:

FieldDescriptionType
payeeThe recipient of the funds from this transaction.String
payment_amountThe transaction amount. This field can include the transaction's currency symbol or code.String
payment_methodThe 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"
}
}
...
}

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 IDDescriptionType
bindid_aliasAlias 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 IDDescriptionType
emailEmail address verified for this user.String
email_verifiedTrue if the email address was verified (e.g., by email OTP); false otherwise.Boolean
email_last_updateTime when the email address was last verified, as a unix-epoch encoded timestamp in seconds.Number

For example:

{
...
"email": "user@acme.com",
"email_verified": true,
"email_last_update": 1605180698
...
}

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 IDDescriptionType
phone_numberMobile phone number verified for this user.String
phone_number_verifiedTrue if the mobile phone number was verified (e.g., by SMS OTP); false otherwise.Boolean
phone_number_last_updateTime when the mobile phone number was last verified, as a unix-epoch encoded timestamp in seconds.Number

For example:

{
...
"phone_number": "+12125556789",
"phone_number_verified": true,
"phone_number_last_update": 1605180698
...
}

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 IDDescriptionType
bindid_network_infoObject 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:

FieldDescriptionType
device_countNumber of devices registered for this BindID user.Number
user_registration_timeTime of the user registration to BindID, as a unix-epoch encoded timestamp in seconds.Number
authenticating_device_registration_timeTime of registration of the authenticating device to BindID, as a unix-epoch encoded timestamp in seconds. This device corresponds to the mobile device for appless mobile authentication; otherwise, it corresponds to the computer.Number
confirmed_capp_countCount of distinct Client Applications that have confirmed this BindID user.Number
user_last_seenTime of the previous BindID flow completed for the user, across all service providers, as a unix-epoch encoded timestamp in seconds.Number
authenticating_device_last_seenTime of the previous BindID flow completed for the user using the current authenticating device across all service providers, as a unix-epoch encoded timestamp in seconds.Number

For example:

{
...
"bindid_network_info": {
"user_registration_time": 1605180498,
"authenticating_device_registration_time": 1605180500,
"authenticating_device_last_seen": 1605180691,
"user_last_seen": 1605180694,
"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.bindid.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_alias": "username@domain",
"email": "user@acme.com",
"email_verified": true,
"email_last_update": 1605180698,
"phone_number": "+12125556789",
"phone_number_verified": true,
"phone_number_last_update": 1605180698,
"bindid_info": {
"capp_first_login_from_authenticating_device": 1605180500,
"authenticating_device": {
"browser_type": "Mobile",
"os_type": "iOS",
"os_version": "14.1",
"browser_version": "Safari"
},
"capp_last_login_from_authenticating_device": 1605180574,
"capp_last_login": 1605180577,
"capp_first_login": 1605180504,
"capp_first_confirmed_login": 1605180577,
"originating_device": {
"browser_type": "Chrome",
"os_type": "Mac OS",
"os_version": "10.15.7",
"browser_version": "86.0.4240.183"
}
},
"bindid_network_info": {
"user_registration_time": 1605180498,
"authenticating_device_registration_time": 1605180500,
"authenticating_device_last_seen": 1605180691,
"user_last_seen": 1605180694,
"confirmed_capp_count": 1,
"device_count": 2
}
}

Failures

The response to an invalid or unauthorized /token request is an HTTP 400 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 NameDescription
Content-TypeReturns application/json
Cache-ControlReturns no-store
PragmaReturns no-cache

Response Body

The JSON object in the body has the following structure:

Field NameDescriptionType
errorSingle ASCII error code—corresponding to the standard OAuth error codes.String

Response Example

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_request"
}