Request Authorization

Once the BindID SDK is initialized, you can invoke a BindID authentication process in two ways—either programmatically, or by specifying an HTML element that will invoke authentication in response to click events.

Using HTML Elements

To request authorization using HTML elements:

Add an HTML element with CSS class xm-bind-id-button, and the attributes below assigned to it. When the element will process the click event, the authentication process will be initiated.

Important: When invoking BindID authorization using HTML elements, you cannot use an HTML button inside an HTML form to invoke the authorization because browsers will reject the request.

Attribute Name	Description
`data-xm-bind-id-on-failure`	Name of the function you create to handle the OIDC authorization failure result. This function receives an error.
`data-xm-bind-id-on-success`	Name of the function you create to handle the OIDC authorization success result. This function isn’t invoked in this version of the SDK (page will redirect if successful).

Here’s an example of a BindID button:

<button class='xm-bind-id-button' data-xm-bind-id-on-success="onSuccess" data-xm-bind-id-on-failure="onFailure">
    Biometric Login</button>

In addition, add the following set of meta tags to the page before the script tag used to load the SDK:

Meta Name	Description
`xm-bind-id-redirect_uri`	URI to which the user-agent will be redirected when the authentication process is completed (which must correspond to one of the allowed URIs configured in the BindID Admin Portal). Redirection will occur as per the OIDC standard. Equivalent to the `redirectUri` parameter of the `authenticate()` SDK call.
`xm-bind-id-nonce`	Optional. Nonce value for the authorization request (as per the OIDC standard). This value will be included in the ID token minted by BindID (see API Reference). Equivalent to the `nonce` parameter of the `authenticate()` SDK call.
`xm-bind-id-state`	Optional. State value for the authorization request (as per the OIDC standard), which will be included in the authorization response sent to the client. Unless disabled, the SDK will verify that the state parameter in the authorization response is identical to the one sent in the request. Equivalent to the `state` parameter of the `authenticate()` SDK call.
`xm-bind-id-scope`	Optional. Set of scopes that will include additional information in the ID Token Claims. Users will be asked for the relevant consent. Available options: `bindid_network_info`, `email`, and `phone`. Equivalent to the `scope` parameter of the `authenticate()` SDK call.
`xm-bind-id-verifications`	Optional. Set of data verifications to request for the user, such as verified phone number (e.g., using SMS OTP). Available options: `phone` and `email`. Equivalent to the `verifications` parameter of the `authenticate()` SDK call.
`xm-bind-id-custom_message`	Optional. Custom message to present on the consent screens, which provides details for the authentication context. Equivalent to the `customMessage` parameter of the `authenticate()` SDK call.
`xm-bind-id-aux_link`	Optional. A URL target for the custom option link presented on the Computer-to-Mobile Options screen, whose prefix must correspond to the one configured in the BindID Admin Portal, and which must begin with `https://` and end with `/`. If not provided, no link will be displayed. Equivalent to `url` of `otherLoginOptions` parameter of the `authenticate()` SDK call.
`xm-bind-id-aux_link_title`	Optional. Title for the custom option link presented on the Computer-to-Mobile Options screen. Equivalent to `title` of `otherLoginOptions` parameter of the `authenticate()` SDK call.
`xm-bind-id-login_hint`	Optional. Hint for the user’s login identifier (e.g., email). Currently, only email is supported and must be specified in the following format: `email:[emailAddress]`, where [emailAddress] is the user's email. Equivalent to `loginHint` parameter of the `authenticate()` SDK call.

For example:

<meta name="xm-bind-id-redirect_uri" content="https://your-rp.example.com">
<meta name="xm-bind-id-nonce" content="12345">
<meta name="xm-bind-id-state" content="demo_state">
<meta name="xm-bind-id-scope" content="bindid_network_info">
<meta name="xm-bind-id-verifications" content="phone email">
<meta name="xm-bind-id-custom_message" content="Login using Your RP">
<meta name="xm-bind-id-aux_link" content="https://your-rp.example.com/more">
<meta name="xm-bind-id-aux_link_title" content="More ways to verify">
<meta name="xm-bind-id-login_hint" content="email:user@email.com">

Using SDK Calls

To request authorization programatically:

Invoke the authenticate() SDK method (see the API reference). This will redirect if successful; otherwise, it will fail. Here’s an example of invoking the authenticate() SDK method—where phone and email is requested, phone and email verification is requested, a link is presented in the Computer-to-Mobile Options screen, custom text is defined for the consent screens, and the user's email is passed:

function invokeBindId() {
    window.XmBindId.authenticate({
        redirectUri: 'https://your-rp.example.com',
        scope: [window.XmBindId.XmBindIdScopeType.Phone, window.XmBindId.XmBindIdScopeType.Email],
        verifications: [window.XmBindId.XmRequiredVerifications.Phone, window.XmBindId.XmRequiredVerifications.Email],
        otherLoginOptions: {
            title: 'More ways to verify',
            url: 'https://your-rp.example.com/more'
        },
        customMessage: 'Login using Your RP',
        loginHint: {
            type: window.XmBindId.XmBindIdLoginHintType.Email,
            value: 'user@email.com'
      }
    }).then(res => {
        onSuccess(res);
    }, err => {
        onFailure(err);
    })
}

Request Authorization#

Using HTML Elements#

Using SDK Calls#

Request Authorization

Using HTML Elements

Using SDK Calls