Passwordless authentication for the modern web
Explore the docs »
View Demo
·
Report Bug
·
Request Feature
Warning
This project is in currently in active development and still not production-ready. You can try it out but expect breaking changes.
Table of Contents
A well-documented REST API that helps developers implement WebAuthn in their web applications faster.
To get a local copy up and running, follow these simple steps.
- Java 22
- Maven
- Docker (or similar) for a local PostgreSQL instance
-
Clone the repo
git clone https://github.com/helioauth/passkeys-api.git
-
Install dependencies
cd passkeys-api-demo ./mvnw install -
Start PostgreSQL server
docker-compose up -d
-
Start the application in development mode
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
The Passkeys API handles all WebAuthn related actions like issuing challenges, verifying signatures, and storing public keys. Your frontend app should request a challenge from the API, pass it to the browser, then return the result.
sequenceDiagram
actor User
participant Browser
participant PasskeyAPI as Passkeys API
participant Authenticator as Device Authenticator
participant Backend as Your Backend
User->>Browser: Initiates registration
Browser->>PasskeyAPI: POST /v1/signup/start (username)
PasskeyAPI->>PasskeyAPI: Generate challenge
PasskeyAPI->>Browser: Return challenge, rpID, userID
Browser->>Authenticator: Create credential (challenge, rpID, userID)
Authenticator->>User: Prompt for biometric/PIN
User->>Authenticator: Provide biometric/PIN
Authenticator->>Browser: Return credential
Browser->>Backend: POST /signup (username, displayName, credential, etc)
Backend->>Backend: Validate user details
Backend->>PasskeyAPI: POST /v1/signup/finish (credential)
PasskeyAPI->>PasskeyAPI: Verify and store credential
PasskeyAPI->>Backend: Return verification result
Backend->>Backend: Store user details
Backend->>Browser: Registration success
Browser->>User: Display success message
sequenceDiagram
actor User
participant Browser
participant PasskeyAPI as Passkeys API
participant Authenticator as Device Authenticator
participant Backend as Your Backend
User->>Browser: Initiates sign-in
Browser->>PasskeyAPI: POST /v1/signin/start (username)
PasskeyAPI->>PasskeyAPI: Generate challenge
PasskeyAPI->>Browser: Return challenge, rpID, allowCredentials
Browser->>Authenticator: Get assertion (challenge, rpID, allowCredentials)
Authenticator->>User: Prompt for biometric/PIN
User->>Authenticator: Provide biometric/PIN
Authenticator->>Browser: Return assertion
Browser->>Backend: POST /login (assertion)
Backend->>PasskeyAPI: POST /v1/signin/finish (assertion)
PasskeyAPI->>PasskeyAPI: Verify assertion
PasskeyAPI->>Backend: Return verification result
Backend->>Browser: Authentication success + session/JWT token in cookie
Browser->>User: Redirect to dashboard
For more examples, please refer to the Demo
- Sign-up and sign-in with passkeys
- Support for more than one passkey per user
- Multitenancy, app projects
- Backup authentication method via magic links, OTP or other
- Administration endpoints for user and credential management
- Support applications that don't have a backend. Generate JWT with custom fields.
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also open an issue with the tag "enhancement". Remember to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the Apache License 2.0. See LICENSE for more information.
HelioAuth: https://helioauth.com/
Project Link: https://github.com/helioauth/passkeys-api