README.md

HelioAuth Passkeys API

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

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

A well-documented REST API that helps developers implement WebAuthn in their web applications faster.

Built With

Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

• Java 22
• Maven
• Docker (or similar) for a local PostgreSQL instance

Installation

1. Clone the repo

   git clone https://github.com/helioauth/passkeys-api.git

2. Install dependencies

    cd passkeys-api-demo
    ./mvnw install

3. Start PostgreSQL server

    docker-compose up -d

4. Start the application in development mode

    ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

(back to top)

Usage

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.

Sign-up flow

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

Loading

Sign-in flow

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

Loading

For more examples, please refer to the Demo

(back to top)

Roadmap

• 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).

(back to top)

Contributing

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!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

License

Distributed under the Apache License 2.0. See LICENSE for more information.

(back to top)

Contact

HelioAuth: https://helioauth.com/

Project Link: https://github.com/helioauth/passkeys-api

(back to top)

Acknowledgments

• java-webauthn-server by Yubico

(back to top)