Skip to main content
Version: v2

Add a passkey

Setting up passkeys for your users involves two main steps:

  1. Create an identity for the user
  2. Bind a passkey to the user's identity and device through a credential binding link

You have two options for setting up passkeys in your application. The options described here are configured via the Configuration Type on the Authenticator Config tab when you add an application.

TypePasskey Support
Hosted WebYou will NOT need to manage creating a user identity and binding a passkey for this user. The Hosted Web Authenticator handles passkey registration and authentication for you, including generating new passkeys, presenting users with authenticator choice options as needed, and validating passkey assertions. Your app simply needs to redirect to Beyond Identity's hosted web authenticator, using an OIDC client - similar to any other Identity Provider (think social providers). For more information, see the Hosted Web. You do not need to continue reading this document.
Embedded SDKYou will need to manage creating a user identity and binding a passkey for this user. Continue reading this document for more information.

Prerequisites

  • Developer account
  • API access token
  • At least one application in a new realm with the Configuration Type set to Embedded SDK.

Create an identity

Before your users can obtain a passkey, they need to be added as a member in a realm. This realm is like a container for different apps, settings and users. Each user needs thier own identity to access an application in that realm.

If your user is creating a new account, you'll want to create an identity with their information, such as email address and username first. Collect this information on your front end and call the /identities API with that information on your back end.

Create an endpoint in your application following the below code example:

note

For more information, visit the add an identity guide.

/identities
1
2
3
4
5
6
curl "https://api-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/identities" \
-X POST \
-H "Authorization: Bearer $(API_TOKEN)" \
-H "Content-Type: application/json" \
-d "{\"identity\":{\"display_name\":\"$(NAME)\",\"traits\": {\"type\": \"traits_v0\",\"username\": \"$(USERNAME)\",
\"primary_email_address\":\"$(EMAIL)\"}}}"

If you prefer, this can be done directly in the Beyond Identity console.

  1. From the Admin Console, under Directory, select Identities > Add identity.

  2. Enter the name, username, and email of the new identity you're adding.

    Add an identity

  3. Click Add Identity.

CHECKPOINT

Now that you have created an identity for a user, you can send the user a link to bind a passkey to their device.

There are two methods to generate a credential binding link. This can be done either through the Beyond Identity console or via API.

Passkey binding methods

Passkeys are created through binding jobs where a binding link gets generated to bind a passkey to a specific device or browser. This passkey gets stored in the user's device's hardware root of trust (i.e., secure enclave).

MethodWhen to use
RETURNYou want to generate a passkey link and deliver it to your users however you wish (in-line, SMS, email, etc.). This is the suggested method to create a passkey without a user leaving your application. It's also the fastest way to get a binding link.
EMAILYou want to send your users an email with a link to create their passkey. Clicking or tapping the link redirects your user to the Beyond Identity Cloud. The Beyond Identity Cloud then looks up the Authenticator Config associated with that passkey creation link. Finally, it redirects your user to your application using the Authenticator Config's Invoke URL specified.

Console

You can send the user a link using the Beyond Identity console. This link can also be sent via email or returned immediately through a generated curl.

  1. In the Admin Console, under Directory, select Identities.

  2. Select the identity you want to bind a passkey to and click Add a passkey.

  3. Select the app that you would like the user to be able to authenticate into and then select one of the two delivery methods:

    • Send an email to user

    • Generate curl for link from the API

    Create a new passkey dialog box

  4. Click Proceed & send email.

    A device enrollment email is sent to your user's primary email address with a link to create their passkey. Clicking or tapping the link redirects your user to the Beyond Identity Cloud. The Beyond Identity Cloud then looks up the Authenticator Config associated with that passkey creation link. Finally, it redirects your user to your application using the Authenticator Config's Invoke URL specified.

API

The RETURN delivery method is the fastest way to get a binding link, which is the link you'll send to your application to complete the passkey binding process. You can deliver the link in-line, SMS, email, etc. This is the suggested method if you want the end user to create a passkey without leaving your application.

  1. Call the endpoint in your application following the below code example.

    /credential-binding-jobs
    1
    2
    3
    4
    curl "https://api-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/identities/$(IDENTITY_ID)/credential-binding-jobs" \
    -X POST \
    -H "Authorization: Bearer $(API_TOKEN)" \
    -H "Content-Type: application/json" \ -d "{\"job\":{\"delivery_method\":\"RETURN\",\"authenticator_config_id\":\"$(AUTHENTICATOR_CONFIG_ID)\"}}"
note
  • You will need the user's IDENTITY_ID from identity creation above. This is the id returned in the response JSON from the create identity API.
  • You can find the REGION, TENANT_ID, REALM_ID and AUTHENTICATOR_CONFIG_ID in your console.
  • You can generate an API_TOKEN from your Beyond Identity Management API application where the token contains the scope credential-binding-jobs:create.

The result of calling this API will be a JSON response with a credential_binding_link.

{
"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"
}
  1. Once you have a binding link generated, feed the credential_binding_link directly into your application's front end using the Embedded SDK to complete the binding process.
tip

Remember to initialize your SDK ahead of time. For more information, see SDK Setup.

const bindResponse = await embedded.bindPasskey(bindingLink);
console.log(bindResponse);

Upon success, a private key will be created in the user's device's hardware trust module, and the corresponding public key will be sent to the Beyond Identity Cloud. At this point, the user has a passkey enrolled on this device and is ready to authenticate.

What can I do next?

After you have a passkey bound to an identity, you're ready to authenticate. See Add authentication for next steps on authentication and token exchange.