This repository provides a sample custom API that exposes all necessary endpoints for passkey creation and login. These endpoints communicate with Corbado's Backend API to manage passkeys.
A Flutter example app is included in the example directory to demonstrate how to use the custom API.
You can use this custom API as a starting point or reference if you need more flexibility — such as implementing custom user flows — when integrating Corbado into your existing application. You can run this API directly, but more commonly, you'll copy its endpoints into your own backend. This allows you to make your backend "passkey-ready" with minimal effort, while Corbado handles the complexity of passkey creation and login.
The custom API is written in TypeScript using the NestJS framework.
🚀 For instructions on integrating this API into your own NestJS backend, see the Integration Guide. 🚀
For the Flutter example app to work end-to-end, session management is required. In this demonstration, we use a simple long-lived JWT as session token for session management.
Please note: this approach is not highly secure and is only intended for demonstration purposes. If you use this custom API in your own project or integrate it with your backend, you must implement your own, more secure session management solution and replace all occurrences of the session token with your own solution.
For more detailed information, see the session management implementation in src/api/session-manager.service.ts. Additionally, a guard is implemented in src/api/session-manager.guard.ts to protect specific endpoints from unauthorized access.
The following sections describe how to run the custom API locally. To run the Flutter example app, please refer to the Flutter example app README.
git clone https://github.com/corbado/custom-api.git
cd custom-apinpm installCopy the example env file and adjust it to your Corbado credentials and environment:
cp .env.example .envEdit .env to set relevant configuration values. Corbado relevant values can be found at https://app.corbado.com.
npm run startThe API should now be running on http://localhost:3000 by default.
The custom API uses the CorbadoService to interact with the Corbado Backend API. This service provides a unified facade for all passkey operations.
The service uses the official Corbado Node.js SDK to interact with the Corbado Backend API and does implement some additional functionality on top of the SDK because some methods are not available in the SDK.
The custom API exposes the following endpoints (detailed information in src/api/api.controller.ts):
| Method | Endpoint | Session Required | Description |
|---|---|---|---|
| POST | /signUpOrLogin |
No | OTP-based signup/login |
| POST | /passkey/append/start |
Yes | Start passkey registration |
| POST | /passkey/append/finish |
Yes | Complete registration |
| POST | /passkey/login/start |
No | Start passkey login |
| POST | /passkey/login/finish |
No | Complete login |
| POST | /passkey/mediation/start |
No | Start conditional login |
| POST | /passkey/mediation/finish |
No | Complete conditional login |
The /signUpOrLogin endpoint provides OTP-based authentication, which is useful as an initial authentication method before users can register passkeys. This endpoint automatically creates a new user if they don't exist (sign up) or authenticates an existing user (login). It returns a session token upon successful authentication, which can then be used to access protected endpoints.
The /passkey/append/* endpoints require a valid session to ensure the user's identity before adding a passkey to their account. Therefore, a session token must be provided for these endpoints.
In contrast, the /passkey/login/* and /passkey/mediation/* endpoints do not require an existing session. These endpoints handle user authentication using passkeys and return a session token upon successful authentication.
These diagrams visualize how the Flutter Example app, the custom API and Corbado interact for the three main flows.
