Skip to main content
Version: v1

SDK Setup

Prerequisites

Overview

This guide enables you to set up each of the Beyond Identity SDKs and to learn about the functionality they contain.

The Embedded SDK offers the entire passkey creation and authentication experience embedded in your product. A set of functions are provided to you through the Embedded namespace. The SDKs support OIDC and OAuth2.

Sample App

JavaScript

Sample App

Sample apps are available to explore. Check out Example for the Embedded SDK.

Installation

yarn add @beyondidentity/bi-sdk-js

or

npm install @beyondidentity/bi-sdk-js

Setup

First, before calling the Embedded functions, make sure to initialize the SDK.

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

const embedded = await Embedded.initialize();

Documentation

JavaScript

Documentation

Documentation is available to explore. Check out SDK API Documentation for the Embedded SDK.

Also, feel free to check out

Binding a Passkey

The bindPasskey function expects a URL. This can either be a binding passkey link fetched directly from our public API, or a binding passkey instruction that is the result of a redirection to your web application. This function should be used in conjunction with isBindPasskeyUrl in order to determine if the URL being passed in is a valid bind passkey URL.

Checkout the Bind Passkey To User guide for more information.

Usage

const bindPasskeyResponse = await embedded.bindPasskey(url);

Where the response type consists of an object containing a Passkey and an optional postBindingRedirectUri URL to redirect to upon succesfully binding a passkey.

{
passkey: Passkey;
postBindingRedirectUri?: string;
}

Authentication

The authenticate function expects a URL and a PasskeyId. This Beyond Identity specific URL is generated during the OAuth2 authorization flow and carries with it a JWT that contains information specific to the current authorization request. When passing this URL into the authenticate function, this will perform a challenge/response against the private key bound to the passkey on your device. You will be required to select from one of the passkeys bound to your device if more than one passkey belongs to a single Realm. This function should be used in conjunction with isAuthenticateUrl in order to determine if the URL being passed in is a valid authenticate URL.

Before calling this function you will need to ask the user to select a passkey that has been bound to the device. A selection view can be built in conjunction with getPasskeys.

Checkout the Authentication with Passkey guide for more information.

Usage

const authenticateResponse = await embedded.authenticate(url, passkeyId);

Where the response consists of an object containing a redirectUrl that you should redirect back to in order to complete the authentication flow, and an optional message to display to the user.

{
redirectUrl: string;
message?: string;
}

URL Validation

Bind Passkey URL Validation

This function is used to validate if a given URL is able to be used by the bindPasskey function.

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

Authenticate URL Validation

This function is used to validate if a given URL is able to be used by the authenticate function.

if (embedded.isAuthenticateUrl(url)) {
// authenticate against a passkey bound to the device
}

Passkey Management

Listing Passkeys

The getPasskeys function enables you to get all passkeys currently bound to the device.

const allPasskeys = await embedded.getPasskeys();

Where the response is a [Passkey].

Deleting a Passkey

The deletePasskey function allows you to delete a passkey given its ID.

await embedded.deletePasskey(passkey.id);