Session Feedback API
The BindID Service exposes an HTTP /session-feedback
endpoint, which can be used to provide feedback on the end-user authentication session. A successful response is an HTTP 200 response, as described below.
HTTP Request
The API is invoked as a POST request to the following endpoint:
where <host-name> has the following value depending on the environment:
- Sandbox:
api.bindid-sandbox.io
- Production:
api.bindid.io
- Production EU:
api.eu.bindid.io
Request Headers
The POST request must include the following HTTP headers:
Header Name | Description |
---|---|
Authorization | Includes authorization for API access. For the header structure, see Introduction. |
Content-Type | Should be set to application/json . |
Request Parameters
The body for this POST request is a JSON object, with the following fields:
Parameter | Description | Type |
---|---|---|
subject_session_at | Required. Access token corresponding to the BindID authentication session for which information is reported. | String |
reports | Required. Array of reports, each encoded as a JSON object (see below). | Array of Reports Objects |
The reports object
array must include exactly one object, with the following structure:
Field | Description | Type |
---|---|---|
type | Required. Should be set to one of the following: authentication_performed , when sending session feedback (primarily for new user BindID authentications, and setting an alias for the user for the first time); alias_updated , when sending session feedback that updates an existing user alias; alias_deleted , when sending session feedback that deletes a user alias. | String |
amr | Optional. For the authentication_performed type, an array of OIDC AMR values identifying the type of additional authentication performed by the service provider directly. | Array of Strings |
time | Required. Unix-epoch encoded timestamp of when authentication was performed, expressed as a number of seconds since 1970-01-01 00:00. You can use the current time at the time of this request. | Number |
alias | Required for alias_updated type; optional for the authentication_performed type. Alias assigned by the service provider to this user for the Client Application, which will be added as the bindid_alias claim to the ID token in subsequent requests. NOTE: Consider that the ID token may be exposed to the client before passing sensitive information in the alias. | String |
Request Examples
The following example sends authentication session feedback and creates a new user alias:
The following example sends authentication session feedback that updates a user alias:
Response Headers
The POST response includes the following HTTP headers:
Header Name | Description |
---|---|
Content-Type | Returns application/json |
Response Body
The JSON object in the body has the following structure:
Field Name | Description | Type |
---|---|---|
status_code | Must be “ok” | String |
Response Example
Failures
In addition to the common errors (see Introduction), the following applicative error response codes may be returned as part of a 200 status response:
Response Code | Description |
---|---|
alias_already_set | An authentication_performed report attempted to update the user’s alias for this Client Application after it has already been set. |
no_alias_to_update | An attempt was made to update an alias that does not exist for this Client Application. |
no_alias_to_delete | An attempt was made to delete an alias that does not exist for this Client Application. |
Additionally, the following bad request error may be returned:
Response Code | Description |
---|---|
missing_new_alias | A new alias was not provided in an alias_updated request. |