UserInfo API

The BindID Service exposes an HTTP OIDC /userinfo endpoint defined by the OIDC standard, which can be used to retrieve information about the authenticated user. A successful response is an HTTP 200 response containing user information, which depends on the scopes requested for the access token.

HTTP Request

The OIDC /userinfo endpoint supports both POST and GET requests. It is available on the BindID Service at:

https://<host-name>/userinfo

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

  • Sandbox: signin.bindid-sandbox.io
  • Production: signin.bindid.io

Request Headers

The request must include the following HTTP header:

Header NameDescription
AuthorizationIncludes authorization for API access. The value should have the following form: Bearer <accesstoken> where <accesstoken> is the access token associated with the request.

Request Example

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

Response Headers

The response includes the following HTTP headers:

Header NameDescription
Content-TypeReturns application/json

Response Body

The JSON object in the body contains the fields described below, which may vary depending on the requested scope for the access token:

Standard Claims

The following claims are always included in userinfo response, as per the OIDC standard:

Claim IDDescriptionType
subExternal User ID (ExtUID) assigned to the authenticated user, which is shared across all service providers. The ExtUID is structured as a UUID.String
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 userinfo response 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 userinfo response 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:

{
"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 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 information 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"
}
}
...
}

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 response 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 response 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 userinfo response 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

Here’s a complete example of the userinfo response:

{
"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": 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

For error responses returned by the UserInfo endpoint, see the OIDC specification - Section 5.3.3