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.identity.security - Production EU:
signin.eu.identity.security
Request Headers
The request must include the following HTTP header:
| Header Name | Description |
|---|---|
Authorization | Includes 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 Name | Description |
|---|---|
Content-Type | Returns 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
- BindID Info Claims
- Feedback Claims
- Email Scope Claims
- Phone Scope Claims
- BindID Network Scope Claims
Standard Claims
The following claims are always included in userinfo response, as per the OIDC standard:
| Claim ID | Description | Type |
|---|---|---|
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 |
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 userinfo response 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 userinfo response 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:
{
"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 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 information object (e.g., in the originating_device claim):
| Field | Description | Type |
|---|---|---|
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": {
"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 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 response 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 response 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 userinfo response 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
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": "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
}
}
Failures
For error responses returned by the UserInfo endpoint, see the OIDC specification - Section 5.3.3