CIBA Authentication API

This API is used to initiate the OIDC Client Initiated Backchannel Authentication Flow (CIBA). This allows service providers to perform out-of-band authentication, such as for authentication flows initiated by IVR systems or Call Centers. CIBA authentication can be requested by sending a POST request to the /authorize_ciba endpoint, and the authentication result can be retrieved from the /token endpoint (see Token API).

HTTP Request

The /authorize_ciba endpoint is available on the BindID Service at:

https://<host-name>/authorize_ciba

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
Content-TypeMust be set to application/x-www-form-urlencoded

Request Body

The body for this POST request is a Form Serialization, with the following fields:

Field NameDescriptionType
client_idRequired. Client identifier issued to the client that requested the authorization.String
client_secretRequired. Client secret provided to the client that requested the authorization.String
scopeRequired. Set of scopes that will include additional information in the ID Token Claims. If needed, users will be asked for the relevant consent. Available options: openid (mandatory), bindid_network_info, phone and email.String
login_hintRequired. A hint regarding the end-user for whom authentication is being requested (see below).Object
binding_messageOptional. Custom message to present on the consent screens, which provides details for the authentication context.String
user_link_custom_messageOptional. A message to present to the end user before the link to initiate the authentication flow. Default is "To verify it's you, click this link".String

The login_hint object contains the following fields:

FieldDescriptionType
sms_targetOptional. The target phone number (including the leading +) to which the link for CIBA authentication should be sent.String

Request Example

POST /authorize_ciba HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: signin.bindid-sandbox.io
client_id=qL4IJvJ1kHwunrLNOGhAAVCMD39EDPWF&client_secret=123&scope=openid&login_hint=%7B%22sms_target%22%3A%22%2B121255555555%22%7D

Response Headers

The response includes the following HTTP headers:

Header NameDescription
Content-TypeReturns application/json
Cache-ControlReturns no-store

Response Body

The JSON object in the body contains the fields described below:

Field NameDescriptionType
auth_req_idRequired. Unique identifier to identify the authentication request, as per CIBA standard. This is used for polling requests to the /token endpoint.String
expires_inRequired. Number of seconds since the authentication request was received until the auth_req_id expires.Number

Response Example

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1",
"expires_in": 120
}

Failures

For error responses returned by a failed CIBA authentication request, see the OIDC CIBA specification - Section 13