Get User Identity and Trust

Every time your users login using BindID, you receive user metadata containing their user identity and trust profile. BindID maintains a trust profile for each user and their devices—such as when the user was first or last seen by you or by any provider integrated with BindID. The user metadata can be obtained from the ID token or UserInfo using backend OIDC APIs, as described below.

User tokens can be obtained by either polling the /token endpoint after the authentication request (poll method), or subscribing to receive a notification for when they’re ready (ping method). Both these modes will also indicate any change in the authentication status, such as if the user initiated the authentication by opening the link you sent.

Get ID and Access Tokens

For each successful authentication, an ID and access token can be retrieved from BindID. The ID token contains the user metadata, as well as trust indicators for the device and authenticator used in the authentication session. The access token can be used in various other API requests, such as to report and retrieve data for the authenticated user.

Using Polling

You can poll the /token endpoint to receive the status of authentication flows and receive the user tokens after the flow has successfully finished.

Note: Only standard polling is supported (see OIDC CIBA standard for more information).

If you want to poll the /token endpoint, here’s what you’ll need to do:

Send a CIBA authentication request with your client credentials to the /authorize_ciba endpoint. The request parameters vary based on whether you want to send the link to the user by SMS or retrieve a direct link (e.g., to embedded in a QR code).
Here is an example of a request that sends a link to a user via SMS:
// Line breaks for readability

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

client_id=d0594078.f5c36acf.tid_4142b590.bindid.io
&client_secret=7d8dd34e-5866-4d11-b37c-d9b9c92c0bba
&scope=openid&channel=%7B%22type%22%3A%22sms%22%2C%20%22
target%22%3A%22%2B19999999999%22%7D
The response contains a unique request ID in the auth_req_id field and a link expiry time:
HTTP/1.1 200 OK
Content-Type: application/json

{
"auth_req_id": "75ad84b5-f160-4436-8fa7-46a59048f991",
"expires_in": 1800
}
Poll the /token endpoint by sending a request that contains the client credentials, request ID, and the grant type (must be urn:openid:params:grant-type:ciba), like this:
// Line breaks for readability

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

auth_req_id=75ad84b5-f160-4436-8fa7-46a59048f991
&client_id=d0594078.f5c36acf.tid_4142b590.bindid.io
&client_secret=7d8dd34e-5866-4d11-b37c-d9b9c92c0bba
&grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba
Until the authentication flow has finished, the response will indicate if the link has been sent to the user or if the user has opened this link. When the link is sent, the response will be:
HTTP/1.1 200 OK
Content-Type: application/json

{
"error": "authorization_pending",
"status": "link_sent"
}
After the user opens the link, the response will be:
HTTP/1.1 200 OK
Content-Type: application/json

{
"error": "authorization_pending",
"status": "link_opened"
}
After the authentication flow is finished, the /token endpoint either returns the user tokens (successful completion) or an error failure message. A successful response looks like this:
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"
}

Using Ping Notifications

If you want to receive notifications about the status of the authentication request, here’s what you’ll need to do:

Make sure you have an HTTPS notification endpoint (Notification URL) registered in the BindID Admin Portal.
Send a CIBA authentication request with your client credentials and a client notification token (client_notification_token) to the /authorize_ciba endpoint. The notification token's value is used as bearer token in the notifications sent by BindID. The other request parameters vary based on whether you want to send the link to the user by SMS or retrieve a direct link (e.g., to embedded in a QR code).
Here is an example of a request that sends a link to a user via SMS:
// Line breaks for readability

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

client_id=d0594078.f5c36acf.tid_4142b590.bindid.io
&client_secret=7d8dd34e-5866-4d11-b37c-d9b9c92c0bba
&scope=openid&channel=%7B%22type%22%3A%22sms%22%2C%20%22
target%22%3A%22%2B19999999999%22%7D
&client_notification_token=8d67dc78-7faa-4d41-aabd-67707b374255
The response contains a unique request ID in the auth_req_id field and a link expiry time:
HTTP/1.1 200 OK
Content-Type: application/json

{
"auth_req_id": "75ad84b5-f160-4436-8fa7-46a59048f991",
"expires_in": 1800
}
When your endpoint receives a notification, you should validate that its bearer token is identical to the value of client_notification_token sent in the CIBA authentication request and then return a 200 status response (see Ping Callback for information about handling failed validations and expired links). If a response is not received within 4 seconds, BindID attempts to resend the notification up to a maximum of 5 times.
You receive notifications when users open a link and when the authentication flow has finished. When the link is opened, the notification will be like this:
POST /ciba-ping-endpoint
content-type: application/json
Authorization: Bearer 8d67dc78-7faa-4d41-aabd-67707b374255

{
"data": {
"topic": "link_status",
"value": "opened",
"auth_request_id": "cf8c5b88-1e99-44d7-9bb5-65bcd6d4f84a",
"client_id": "d0594078.f5c36acf.tid_4142b590.bindid.io"
}
}
When the authentication finished successfully, the notification will be similar to this:
POST /ciba-ping-endpoint
content-type: application/json
Authorization: Bearer 8d67dc78-7faa-4d41-aabd-67707b374255

{
"data": {
"topic": "auth_completed",
"value": "success",
"auth_request_id": "75ad84b5-f160-4436-8fa7-46a59048f991",
"client_id": "d0594078.f5c36acf.tid_4142b590.bindid.io"
}
}
If the authentication fails, the notification will be something like:
POST /ciba-ping-endpoint
content-type: application/json
Authorization: Bearer 8d67dc78-7faa-4d41-aabd-67707b374255

{
"data": {
"topic": "auth_completed",
"value": "failure",
"auth_request_id": "75ad84b5-f160-4436-8fa7-46a59048f991",
"client_id": "d0594078.f5c36acf.tid_4142b590.bindid.io"
}
}
After the authentication flow is finished, call the /token endpoint to retrieve the user tokens (successful completion) or the failure error message. The call must include the client credentials, the request ID (auth_request_id), and the grant type (must be urn:openid:params:grant-type:ciba), for example:
// Line breaks for readability

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

auth_req_id=75ad84b5-f160-4436-8fa7-46a59048f991
&client_id=d0594078.f5c36acf.tid_4142b590.bindid.io
&client_secret=7d8dd34e-5866-4d11-b37c-d9b9c92c0bba
&grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba

Get User Information

You can also obtain the user metadata from the OIDC /userinfo endpoint, for example, if required for your OIDC implementation. Send an HTTP GET or POST request to the OIDC /userinfo endpoint. The Authorization header should include the access token returned in the /token response in the access_token field. See the UserInfo API reference.

For example:

GET /userinfo HTTP/1.1
Authorization: Bearer f3uv87HG87
Host: signin.bindid-sandbox.io

The /userinfo response includes the user metadata directly in the body.

For example:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "sub": "123e4567-e89b-12d3-a456-426652340000",
   "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": {
         "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": "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
   }
}

Handle User Token

The user metadata may correspond to a user that's already known to BindID or a new user:

If the user is unknown to BindID, the ID token (and UserInfo response) will not include the bindid_alias claim. The application should respond by taking the user through a registration process where the application establishes user identity (see Send Session Feedback). Afterwards, the application should set a BindID alias for the user so that subsequent logins will be associated with it.
If the user is known to BindID, the ID token (and UserInfo Response) will include the bindid_alias claim. Your application should look up this value within its user-store to identify the application user to which this alias is registered, and use that user for the rest of the session.

Get User Identity and Trust#

Get ID and Access Tokens#

Using Polling#

Using Ping Notifications#

Get User Information#