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:

https://<host-name>/session-feedback

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 NameDescription
AuthorizationIncludes authorization for API access. For the header structure, see Introduction.
Content-TypeShould be set to application/json.

Request Parameters

The body for this POST request is a JSON object, with the following fields:

ParameterDescriptionType
subject_session_atRequired. Access token corresponding to the BindID authentication session for which information is reported.String
reportsRequired. 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:

FieldDescriptionType
typeRequired. 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
amrOptional. 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
timeRequired. 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
aliasRequired 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:

POST /session-feedback HTTP/1.1
Content-Type: application/json
Authorization: BindIdBackend AccessToken hjg2khf236ghf; Zgoptaz...c1lYTM3..Dg4NYzND...MjQ4hNg
{
"subject_session_at": "hjg2khf236ghf",
"reports": [
{
"type": "authentication_performed",
"amr": ["pwd"],
"time": 1596189540,
"alias": "username@domain"
}
]
}

The following example sends authentication session feedback that updates a user alias:

POST /session-feedback HTTP/1.1
Content-Type: application/json
Authorization: BindIdBackend AccessToken hjg2khf236ghf; Zgoptaz...c1lYTM3..Dg4NYzND...MjQ4hNg
{
"subject_session_at": "hjg2khf236ghf",
"reports": [
{
"type": "alias_updated",
"time": 1653462353,
"alias": "updated-alias@domain"
}
]
}

Response Headers

The POST response includes the following HTTP headers:

Header NameDescription
Content-TypeReturns application/json

Response Body

The JSON object in the body has the following structure:

Field NameDescriptionType
status_codeMust be “ok”String

Response Example

HTTP/1.1 200 OK
Content-Type: application/json
{
"status_code": "ok"
}

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 CodeDescription
alias_already_setAn authentication_performed report attempted to update the user’s alias for this Client Application after it has already been set.
no_alias_to_updateAn attempt was made to update an alias that does not exist for this Client Application.
no_alias_to_deleteAn 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 CodeDescription
missing_new_aliasA new alias was not provided in an alias_updated request.