JavaScript/TypeScript SDK
A lean, type-safe, fetch-based API client for the Hanko Passkey API
The @teamhanko/passkeys-sdk package lets you call the Hanko Passkey API from JavaScript/TypeScript that supports fetch.
This includes Node.js, Browsers, Deno, Bun, and frameworks like Next.js, Astro, and SvelteKit.
Usage
A tenant is an API client instance for one tenant of the Hanko Passkey API.
If you use Hanko Cloud, get your tenant ID and API key from the dashboard.
Create a new tenant instance:
const passkeyApi = tenant({
tenantId: "<your tenant id>",
apiKey: "<your secret api key>",
});
- If you only use public API methods, like
/login/initialize, you can omit theapiKey. - If you’re self-hosting the Passkey API, make sure to pass the
baseUrlas well.
Now you’re ready to call the API. For example, to start the process of registering a new passkey:
const creationOptions = await tenant.registration.initialize({
userId: "<id of the user in your database>",
username: "<username of the user>",
});
Example Implementation
Install the SDK
Get your tenant ID and API key
Get your tenant ID and API key from Hanko Cloud and add them to your .env file.
PASSKEYS_API_KEY=your-api-key
PASSKEYS_TENANT_ID=your-tenant-id
Allow users to register passkeys as a login method
On your backend, you’ll have to call tenant({ ... }).registration.initialize() and registration.finalize() to create and store a passkey.
import { tenant } from "@teamhanko/passkeys-sdk";
import dotenv from "dotenv";
import db from "../db.js";
dotenv.config();
const passkeyApi = tenant({
apiKey: process.env.PASSKEYS_API_KEY,
tenantId: process.env.PASSKEYS_TENANT_ID,
});
async function startServerPasskeyRegistration(userID) {
const user = db.users.find((user) => user.id === userID);
const createOptions = await passkeyApi.registration.initialize({
userId: user.id,
username: user.email || "",
});
return createOptions;
}
async function finishServerPasskeyRegistration(credential) {
await passkeyApi.registration.finalize(credential);
}
async function handlePasskeyRegister(req, res) {
const { user } = req;
const userID = user.id;
if (!userID) {
return res.status(401).json({ message: "Unauthorized" });
}
console.log("userId", userID);
const { start, finish, credential } = req.body;
try {
if (start) {
const createOptions = await startServerPasskeyRegistration(userID);
console.log("registration start");
return res.json({ createOptions });
}
if (finish) {
await finishServerPasskeyRegistration(credential);
return res.json({ message: "Registered Passkey" });
}
} catch (error) {
return res.status(500).json(error);
}
}
Frontend
On your frontend, the registerPasskey() function handles the passkey registration process. It first sends a request to the server to initiate the registration process and receives the response for creating a new passkey.
It then uses the @github/webauthn-json library to create a new passkey credential based on the received options from the response. Finally, it sends another request to the server with the newly created credential to complete the registration process.
async function registerPasskey() {
const createOptionsResponse = await fetch("http://localhost:5001/api/passkeys/register", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: 'include',
body: JSON.stringify({ start: true, finish: false, credential: null }),
});
const { createOptions } = await createOptionsResponse.json();
console.log("createOptions", createOptions)
const credential = await create(
createOptions as CredentialCreationOptionsJSON,
);
console.log(credential)
const response = await fetch("http://localhost:5001/api/passkeys/register", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: "include",
body: JSON.stringify({ start: false, finish: true, credential }),
});
console.log(response)
if (response.ok) {
toast.success("Registered passkey successfully!");
return;
}
}
Allow users to log in with passkeys
async function startServerPasskeyLogin() {
const options = await passkeyApi.login.initialize();
return options;
}
async function finishServerPasskeyLogin(options) {
const response = await passkeyApi.login.finalize(options);
return response;
}
async function handlePasskeyLogin(req, res) {
const { start, finish, options } = req.body;
try {
if (start) {
const loginOptions = await startServerPasskeyLogin();
return res.json({ loginOptions });
}
if (finish) {
const jwtToken = await finishServerPasskeyLogin(options);
const userID = await getUserID(jwtToken?.token ?? "");
console.log("userID from hanko", userID);
const user = db.users.find((user) => user.id === userID);
if (!user) {
return res.status(401).json({ message: "Invalid user" });
}
console.log("user", user);
const sessionId = uuidv4();
setUser(sessionId, user);
res.cookie("sessionId", sessionId);
return res.json({ message: " Passkey Login successful" });
}
} catch (error) {
console.error(error);
return res
.status(500)
.json({ message: "An error occurred during the passke login process." });
}
}
Frontend
async function signInWithPasskey() {
const createOptionsResponse = await fetch("http://localhost:5001/api/passkeys/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: 'include',
body: JSON.stringify({ start: true, finish: false, credential: null }),
});
const { loginOptions } = await createOptionsResponse.json();
// Open "register passkey" dialog
const options = await get(
loginOptions as any,
);
const response = await fetch("http://localhost:5001/api/passkeys/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: 'include',
body: JSON.stringify({ start: false, finish: true, options }),
});
if (response.ok) {
console.log("user logged in with passkey")
navigate("/dashboard")
return;
}
}
Try it yourself
Check out sample apps made using the SDK:
Was this page helpful?