Send Activation API

Sends a link to users that, when opened, initiates a BindID registration flow. By default, the link is sent via email and is valid for 30 minutes from the time it is sent. 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.

Note: To enable BindID registrations via links, you need to add a client redirect URI (see BindID Registration Links).

HTTP Request

The API is invoked as a POST request to the following endpoint:

https://<host-name>/api/v1/mgmt/send-activation

where <host-name> has the following value depending on the environment:

Sandbox: admin.bindid-sandbox.io
Production: admin.bindid.io
Production EU: admin.eu.bindid.io

Request Header

Header Name	Value
`Authorization`	A valid bearer token (see Token API)
`Content-Type`	`application/json`

Request Body

A JSON object with these fields:

Field	Description	Type
`alias`	Object containing the user alias that is stored in BindID after the user registers using the link. Required when `confirmedUser` is unspecified or set to `true`.	alias
`clientId`	Required. The client ID of the client for which the user will be authenticated.	String
`customMessage`	Optional. Message displayed to the user during the BindID authentication flow.	String
`scopes`	Required. Array of required scopes. These values are supported: `email` and `phone`. Can be an empty array.	Array of Strings
`completionMessage`	Optional. Object containing a message and link that is displayed to the user after completing the authentication flow.	completionMessage
`credentialsId`	Required. API credentials ID used to create the access token that authorizes this request.	String
`secondaryCompletionMessage`	Optional. Message displayed to the user on a mobile device during a desktop to mobile authentication flow.	String
`userEmail`	Required. Email address to which the link is sent and the user is registered.	String
`verifications`	Required. Array of required verifications. These values are supported: `ts.bindid.iac.email` and `ts.bindid.iac.phone_number`.	Array of Strings
`confirmedUser`	Optional. Determines if the user's device is bound to the client application after the user successfully registers (equivalent to calling the Session Feedback API after authenticating a new user). When unspecified, defaults to `true`.	Boolean

alias Object

Field	Description	Type
`type`	Required. Can be `none`, `email` or `alias`. When `email` is specified, the user alias is set to the value of the email address used to send the link and register the user (`userEmail`).	String
`value`	The user's alias. Only required when `type` is set to `alias`.	String

completionMessage Object

Field	Description	Type
`text`	Required. Text to display to the user on the authentication completed page.	String
`link`	Optional. Object that defines a link displayed to the user on the authentication completed page: `redirectUri` (string, required) - the link's URL; `label` (string, required) - the link's display text. The URL must be listed as a client redirect URI in the Admin Portal (see Configure Your Application).	Object

Request Example

POST /api/v1/mgmt/send-activation
Authorization: Bearer k_lONS-upqKzUx_UWpmJBIiybpf2ZyEkmBTcUYkvSEI
Content-Type: application/json

{
    "clientId": "3d70edce.23bf0963.tid_7d4bd3fc.bindid.io",
    "credentialsId": "55b9e897.management_api_app.tid_7d4bd3fc.bindid.io",
    "verifications": [
        "ts.bindid.iac.email",
        "ts.bindid.iac.phone_number"
    ],
    "userEmail": "someone@email.com",
    "scopes": [
        "email",
        "phone"
    ],
    "confirmedUser": true,
    "alias": {
        "type": "email"
    },
    "customMessage": "Nearly done...",
    "secondaryCompletionMessage": "Go back to your desktop to finish registering your device.",
    "completionMessage": {
        "text": "Welcome to ACME",
        "link": {
            "redirectUri": "https://www.acme.com",
            "label": "Go to our portal"
        }
    }
}

Response Headers

The POST response includes this HTTP header:

Header Name	Value
`Content-Type`	`application/json`

Response Body

The JSON object in the body has the following structure:

Field Name	Description	Type
`status`	Indicates call success.	String
`activationResult`	Object that contains result data for registration links that were sent.	activationResult

activationResult Object

Field	Description	Type
`channelsResult`	Indicates success or failure of each channel to which registration links were sent. Currently, only one channel is supported.	Array of channelsResult objects

channelsResult Object

Field	Description	Type
`channelType`	The channel used to send the link. Currently, only email is supported.	String
`target`	The email address to which the registration link was sent.	String
`status`	Indicates whether or not the link was successfully sent.	String

Response Example

HTTP/2 200
Content-Type: application/json

{
    "status": "success",
    "activationResult": {
        "channelsResult": [
            {
                "channelType": "email",
                "target": "someone@email.com",
                "status": "success"
            }
        ]
    }
}

Send Activation API#

HTTP Request#

Request Header#

Request Body#

alias Object#

completionMessage Object#

Request Example#

Response Headers#

Response Body#

activationResult Object#

channelsResult Object#

Response Example#