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.
Additionally, service providers can use the CIBA API to receive a direct link for use in native desktop to mobile authentication flows, instead of sending end users to the BindID QR screen to authenticate. When calling the API to receive a direct link, the response contains an authentication link that can be encoded as a QR code and displayed to the end user in a native application.
CIBA authentication can be requested by sending a POST request to the /authorize_ciba endpoint. The status of links sent to end users and authentication results can be retrieved in one of these ways:
- Poll mode: polling the
/tokenendpoint (see Token API). - Ping mode: BindID sends a notification to the endpoint specified for the client in the Admin Portal.
HTTP Request
The /authorize_ciba endpoint is available on the BindID Service at:
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 |
|---|---|
Content-Type | Must 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 Name | Description | Type |
|---|---|---|
client_id | Required. Client identifier issued to the client that requested the authorization. | String |
client_notification_token | Required for CIBA ping mode. Bearer token used by the client to authenticate CIBA ping notifications (Authorization request header). | String |
client_secret | Required. Client secret provided to the client that requested the authorization. | String |
scope | Required. 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 |
channel | Required. Object containing either a phone number for SMS flows or an indication that a direct link is requested for a native desktop-to-mobile authentication flow. | channel |
acr_values | Optional. Requested ACR values, specified as a space-separated string. Available options: ts.bindid.iac.email (to require a verified email address) and ts.bindid.iac.phone_number (to require a verified phone number). Equivalent to the verifications parameter of the authenticate() SDK call. | String |
claims | Optional. Object containing claims to return in the ID token (only id_token is supported). The structure is per the OIDC Standard. These claims are supported: bindid_psd2_transaction - for transaction signing requests; bindid_approval - for custom BindID approval requests. | claims |
login_hint | Optional. Hint for the user’s login identifier (e.g., email). Currently, only email is supported. | String |
bound_to | Optional. Used to require an authenticating device that was previously confirmed for the specified user (e.g., for step-up authentication). A confirmed device is a device bound to the Client Application for the user (via /session-feedback API), as reflected in the ID token by the ts.bindid.app_bound_cred ACR value. This parameter should specify the user identifier in the following format: [identifierType]:[identifierValue], where [identifierType] can either be alias (user alias) or sub (subject of the ID token). Equivalent to boundTo parameter of the authenticate() SDK call. | String |
binding_message | Optional. Custom message to present on the consent screens, which provides details for the authentication context. | String |
ui_locales | Optional. Preferred languages for the user interface, specified as a space-separated list of language tag values [RFC5646], ordered by preference. | String |
channel Object
Here is the structure of the channel object:
| Field | Description | Type |
|---|---|---|
type | Required. Either direct_link for direct link flows, or sms for SMS flows. | String |
target | Optional. For SMS flows, the target phone number (including the leading +) to which the link for CIBA authentication should be sent. | String |
user_link_custom_message | Optional. For SMS flows, a message presented to the end user in the SMS before the link to initiate the authentication flow. Default is "To verify it's you, click this link". | String |
claims Object
Here is the structure of value when requesting any type of claim:
| Field | Description | Type |
|---|---|---|
display_data | Required. Object containing data displayed to the user as part of the approval request, as described below. | Object |
additional_data | Optional. Additional data about the approval request that is not displayed to the user but returned in the ID token. | Object |
bindid_psd2_transaction Claim
Here is the structure of the display_data object for value for a bindid_psd2_transaction claim:
| Field | Description | Type |
|---|---|---|
payee | Required. Requested payment recipient. | String |
payment_amount | Required. Requested payment amount, including the currency symbol (such as $100.50). | String |
payment_method | Required. Requested payment method (such as Acme Card). | String |
Here is an example of the structure of a bindid_psd2_transaction claims object:
bindid_approval Claim
Here is the structure of the display_data object for value for a bindid_approval claim:
| Field | Description | Type |
|---|---|---|
main_attribute | Optional. Object containing the main attribute of the approval request, which is emphasized in the UI consent screen. It contains these fields: label (required, string) and value (required, string). | Object |
attributes | Required. Array of attributes displayed to the user as part of the approval request, used to provide authentication context details. Each array element has these fields: label (required, string), value (required, string), and icon (optional, string, see below). When the icon field is not specified, the Payment icon is used. The array can contain a maximum of two elements. | Array of objects |
icon Field Values
The icon field can contain these values:
| Value | Icon |
|---|---|
Payment |  |
Locations |  |
Contract |  |
Email |  |
SmartPhone |  |
Id |  |
Edit |  |
Calendar |  |
Lock |  |
Globe |  |
Here is an example of the structure of a bindid_approval claims object:
Request Example
Here's an example of an /authorize_ciba request for an SMS flow using polling mode:
Here's an example of an /authorize_ciba request for a direct link flow using polling mode:
Here's an example of an /authorize_ciba request for an SMS flow using ping mode:
Response Headers
The response includes the following HTTP headers:
| Header Name | Description |
|---|---|
Content-Type | Returns application/json |
Cache-Control | Returns no-store |
Response Body
The JSON object in the body contains the fields described below:
| Field Name | Description | Type |
|---|---|---|
auth_req_id | Unique identifier to identify the authentication or transaction signing request, as per CIBA standard. This is used for polling requests to the /token endpoint. | String |
expires_in | Number of seconds since the authentication request was received until the auth_req_id expires. | Number |
link | Authentication link to display to the end user. Returned as part of a direct link flow. | String |
interval | Polling request interval in seconds. Returned as part of a direct link flow with a value of 1. | Number |
Note: By default, links expire after 30 minutes. To change this, contact your Transmit representative to enable a preview feature where the expiration time can be set on the Application's settings page in the Admin Portal.
Response Example
Here's an example of an /authorize_ciba response for an SMS authentication or transaction flow:
Here's an example of an /authorize_ciba response for a direct link flow:
Failures
For error responses returned by a failed CIBA authentication request, see the OIDC CIBA specification - Section 13