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

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 authentication_performedString
amrOptional. 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
aliasOptional. 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. Once an alias is set, it cannot be updated. NOTE: Consider that the ID token may be exposed to the client before passing sensitive information in the alias.String

Request Example

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"
}
]
}

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

Response CodeDescription
alias_already_setAn attempt was made to update the user’s alias for this Client Application after it was already set.