Flow Initialization API
The BindID Service exposes an HTTP /interactive/init endpoint, which allows end users to start interactive BindID flows (such as registering new trusted devices). The endpoint returns a URL that is used to initiate the interactive flow, for example, by linking it to an Add Device button in your application (see Interactive API).
HTTP Request
The API is invoked as a POST request to the following endpoint:
https://<host-name>/api/v1/interactive/init
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 |
|---|---|---|
redirect_uri | Required. URI to which the user's browser is redirected after completing the interactive flow. | String |
purpose | Required. Currently, must be device_enrollment, which enables end users to add a new trusted mobile device to their BindID account. | String |
state | Optional. State value for the authorization request, returned in the redirect response. | String |
data | Optional. Reserved for future use. | Object |
Request Example
POST /api/v1/interactive/init HTTP/1.1
Content-Type: application/json
Authorization: BindIdBackend AccessToken to33lpl...zW7BM; bGAH...FnzcaYvFf6djg=
{
"redirect_uri": "https://www.acme.com/device_registered",
"purpose": "device_enrollment"
}
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 | Indicates call success. | String |
data | Object containing the URL used to initiate an end-user BindID interactive flow. | data |
data Object
| Field Name | Description | Type |
|---|---|---|
url | URL for initiating an end-user BindID interactive flow (see Interactive API). | String |
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"status_code": "ok",
"data": {
"url": "https://my.bindid.io/interactive?t=wXgEg-BrTJWfR2NkGPrimQ&fid=BID_d5312de8"
}
}