Skip to main content
Version: v2

bindPasskey

Last updated on

The bindPasskey function enables your app to generate and bind a new passkey to an identity. The identity can be one that you create via the Beyond Identity API or one that exists already in the tenant you target.

This is a reference article that describes the bindPasskey function. For a complete walk-through on creating a new passkey, see our guide Bind Passkey to an identity.

Dependencies​

The bindPasskey function requires the Beyond Identity SDK.

yarn add @beyondidentity/bi-sdk-js

or

npm install @beyondidentity/bi-sdk-js

Prerequisites​

Before making a call to bindPasskey, you must complete the following prerequisite calls:

  1. Import the required types and functions from the SDK.

    import { Embedded } from '@beyondidentity/bi-sdk-js';

  2. Initialize the SDK.

    // --- Initialize with required arguments
    try {
      const embedded = await Embedded.initialize();
      console.log("Initialization successful", embedded);
    } catch (error) {
      console.error("Initialization failed:", error);
    }

    // --- Initialize with required and optional arguments
    const config = {
      allowedDomains: ["example.com", "another-example.com"],
      logger: function (logType, message) {
        console.log(`[${logType}] ${message}`);
      },
    };

    try {
      const embedded = await Embedded.initialize(config);
      console.log("Initialization successful", embedded);
    } catch (error) {
      console.error("Initialization failed:", error);
    }

  3. Get a passkey binding link URL using the Beyond Identity API.

    Generating a passkey binding link has several inputs and options. For details, see passkey-binding-jobs.

  4. Use isBindPasskeyUrl to verify passkey binding link.

    if (embedded.isBindPasskeyUrl(url)) {
      // bind the passkey using `bindPasskey`
    }

Parameters​

ParameterTypeDescription
urlstringRequired. Passkey binding link URL. Using our public API, this can be fetched directly or sent to the email address associated with the identity. This URL enables bindPasskey to kick off the passkey creation and binding sequence for the identity that you specify.

Returns​

On success, the bindPasskey function returns a Promise that resolves to a BindPasskeyResponse, which itself is an object that contains the following keys:

  • passkey: an object representing the newly created passkey. See example passkey.

  • postBindRedirect: a string containing the URL to redirect to upon successfully binding a passkey. This is the URL that you specified in the earlier call to the API to get the passkey binding link

Notes​

Call this function from client-side code, as it needs to run in either in the browser or natively on iOS/Android.

Examples​

Example: Call bindPasskey after validating passkey binding URL​

const url = "credential-binding-url";

if (EmbeddedSdk.isBindPasskeyUrl(url)) {
  // The URL is valid for binding a passkey
  EmbeddedSdk.bindPasskey(url)
    .then(response => {
      console.log("Success:", response);
    })
    .catch(err => {
      console.error("Error:", err.message);
    });
} else {
  console.log("The URL is not a valid Bind Passkey URL");
}

Example: Create an identity and get passkey binding URL​

In this example, you'll first create a new identity using the API, then generate and retrieve the passkey binding URL.

To achieve this, we use several data elements:

  1. Configuration from your BI tenant:

    PropertyDescription
    TENANT_IDThe Tenant ID of the tenant in which the app is configured.
    REALM_IDThe Realm ID of the realm in which the app is configured.
    AUTHENTICATOR_CONFIG_IDThe Authenticator Config ID from the Authenticator Config tab of the app's configuration page.

  2. Other passkey binding API parameters:

    PropertyDescription
    delivery_methodSelect RETURN to deliver the URL directly in the response.
    post_binding_redirect_uriAn optional parameter that specifies a URL the user gets redirected to after a successful binding (see Returns above).

  3. The identityId returned from the first call is used for the second call.

  4. A username passed into the function is used to create the user and establish their email name

You can find the resulting passkey binding URL in the credential_binding_link member of the response JSON returned from the second call.

Create a New Identity​

Create New Identity
1
2
3
4
5
6
curl -X POST \
"${API_URL}/v1/tenants/${TENANT_ID}/realms/${REALM_ID}/identities" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d "{ "identity": { "display_name": "${DISPLAY_NAME}", "traits": { "type": "traits_v0", "username": "${USERNAME}", "primary_email_address": "${EMAIL}" } }
}"

Where the response JSON will look like:

{
  "id": "e372db224c06e850",
  "realm_id": "8f5bec58229e6f29",
  "tenant_id": "0001f1f460b1ace6",
  "display_name": "Test Identity",
  "create_time": "2022-04-12T05:53:07.119Z",
  "update_time": "2022-06-16T14:31:03.770Z",
  "traits": {
    "type": "traits_v0",
    "username": "test",
    "primary_email_address": "test@example.com"
  }
}
Get Credential Binding Link for Identity
1
2
3
4
5
6
curl -X POST \
"${API_URL}/v1/tenants/${TENANT_ID}/realms/${REALM_ID}/identities/${IDENTITY_ID}/credential-binding-jobs" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d "{ "job": { "delivery_method": "RETURN", "authenticator_config_id": "${AUTHENTICATOR_CONFIG_ID}", "post_binding_redirect_uri": "http://example.com" }
}"

Where the response JSON will look like:

{
  "credential_binding_job": {
    "id": "c4fc2d753ca22b14",
    "realm_id": "cdf4862dc4d49791",
    "tenant_id": "000183a77dd50fa9",
    "identity_id": "87fabad6956c6d4b",
    "delivery_method": "RETURN",
    "state": "LINK_SENT",
    "post_binding_redirect_uri": "http://example.com/callback",
    "authenticator_config_id": "67bb0acf12e5c899",
    "expire_time": "2022-03-21T03:42:52.905Z",
    "create_time": "2022-03-14T03:42:52.905Z",
    "update_time": "2022-03-15T05:55:23.823Z"
  },
  "credential_binding_link": "http://example.com/v1/tenants/000183a77dd50fa9/realms/cdf4862dc4d49791/identities/87fabad6956c6d4b/credential-binding-jobs/c4fc2d753ca22b14:invokeAuthenticator?token=1St9IKIIrYyQ8sOSeuk5UkbLKnBJhuD4I7nWIqt-BNANDEFS-XVuOHxB7TFdZcRm"
}

From the response above, you can see that the required binding URL is returned in the credential_binding_link member of the response JSON. This is the URL that you will pass into the bindPasskey function.

Example: Get passkey binding URL for existing identity​

To obtain a passkey binding URL for an existing identity, you will first need to retrieve the identity ID for a known user:

Retrieve existing identity
1
2
curl -X GET "https://${API_URL}/v1/tenants/${TENANT_ID}/realms/${REALM_ID}/identities?filter=username%20eq%20%22john%22" \
-H "Authorization: Bearer ${API_TOKEN}"

Where the response JSON will look like:

{
  "identities": [
    {
      "id": "e372db224c06e850",
      "realm_id": "8f5bec58229e6f29",
      "tenant_id": "0001f1f460b1ace6",
      "display_name": "Test Identity",
      "create_time": "2022-04-12T05:53:07.119Z",
      "update_time": "2022-06-16T14:31:03.770Z",
      "traits": {
        "type": "traits_v0",
        "username": "test",
        "primary_email_address": "test@example.com"
      }
    }
  ],
  "total_size": 1
}

You can then use the identity ID to obtain the credential binding URL:

Get Credential Binding Link for Identity
1
2
3
4
5
6
curl -X POST \
"${API_URL}/v1/tenants/${TENANT_ID}/realms/${REALM_ID}/identities/${IDENTITY_ID}/credential-binding-jobs" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d "{ "job": { "delivery_method": "RETURN", "authenticator_config_id": "${AUTHENTICATOR_CONFIG_ID}", "post_binding_redirect_uri": "http://example.com" }
}"

Where the response JSON will look like:

{
  "credential_binding_job": {
    "id": "c4fc2d753ca22b14",
    "realm_id": "cdf4862dc4d49791",
    "tenant_id": "000183a77dd50fa9",
    "identity_id": "87fabad6956c6d4b",
    "delivery_method": "RETURN",
    "state": "LINK_SENT",
    "post_binding_redirect_uri": "http://example.com/callback",
    "authenticator_config_id": "67bb0acf12e5c899",
    "expire_time": "2022-03-21T03:42:52.905Z",
    "create_time": "2022-03-14T03:42:52.905Z",
    "update_time": "2022-03-15T05:55:23.823Z"
  },
  "credential_binding_link": "http://example.com/v1/tenants/000183a77dd50fa9/realms/cdf4862dc4d49791/identities/87fabad6956c6d4b/credential-binding-jobs/c4fc2d753ca22b14:invokeAuthenticator?token=1St9IKIIrYyQ8sOSeuk5UkbLKnBJhuD4I7nWIqt-BNANDEFS-XVuOHxB7TFdZcRm"
}

From the response above, you can see that the required binding URL is returned in the credential_binding_link member of the response JSON. This is the URL that you will pass into the bindPasskey function.

Example: Get credential binding URL via email​

The following example shows how to obtain a credential binding URL for a known identity ID via email.

Send Credential Binding Link for Identity Over Email
1
2
3
4
curl -X POST "${API_URL}/v1/tenants/${TENANT_ID}/realms/${REALM_ID}/identities/${IDENTITY_ID}/credential-binding-jobs" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "Content-Type: application/json" \
-d "{ "job": { "delivery_method": "${EMAIL}", "authenticator_config_id": "${AUTHENTICATOR_CONFIG_ID}", "post_binding_redirect_uri": "http://example.com" } }"

Where the response JSON will look like:

{
  "credential_binding_job": {
    "id": "c4fc2d753ca22b14",
    "realm_id": "cdf4862dc4d49791",
    "tenant_id": "000183a77dd50fa9",
    "identity_id": "87fabad6956c6d4b",
    "delivery_method": "EMAIL",
    "state": "LINK_SENT",
    "post_binding_redirect_uri": "http://example.com/callback",
    "authenticator_config_id": "67bb0acf12e5c899",
    "expire_time": "2022-03-21T03:42:52.905Z",
    "create_time": "2022-03-14T03:42:52.905Z",
    "update_time": "2022-03-15T05:55:23.823Z"
  }
}

Notice how "credential_binding_link" is not in the response payload since it was sent over email.

When the user clicks the link in the Beyond Identity registration email, they will be redirected to your application's Invoke URL, as configured in the Authenticator Config tab in your BI tenant, with an automatically appended '/bind' route, for example, 'http://example.com/bind', with several query string parameters appended.

Your app must have a route or page to intercept this redirect, and send it to the bindPasskey function as follows:

const url = "credential-binding-url";

if (EmbeddedSdk.isBindPasskeyUrl(url)) {
  // The URL is valid for binding a passkey
  EmbeddedSdk.bindPasskey(url)
    .then(response => {
      console.log("Success:", response);
    })
    .catch(err => {
      console.error("Error:", err.message);
    });
} else {
  console.log("The URL is not a valid Bind Passkey URL");
}

For complete guidance on binding a passkey to a user, see Bind Passkey to an identity.