canonical: https://jentic.com/apis/hanko.io/hanko

# Hanko API

Hanko is an open-source authentication platform built around passkeys and WebAuthn, with passcode email OTP fallback and a flow-based state machine that drives registration, login, and profile updates. The public API exposes 11 endpoints split between user-facing authentication flows and an admin API for managing users and audit logs. End-user calls return short-lived JWTs verifiable against the JWKS endpoint, while admin endpoints require an API key in the Authorization header. The flow-based design lets a single endpoint advance multiple authentication steps without bespoke client logic.

## For AI agents

Run passkey, WebAuthn, and email OTP authentication flows and manage users and audit logs through a flow-based REST API.

## Scope

Does not handle SMS OTP delivery, payments, or session storage outside of JWT issuance - use for passkey, WebAuthn, and email OTP authentication flows only.

## Capabilities

- Drive a passkey-first registration, login, or profile flow through a single state machine endpoint
- Issue and verify JWTs via the standard JWKS endpoint for downstream services
- Send and verify email OTP passcodes as a fallback for passkey-less devices
- List, create, fetch, and delete users on the admin API
- Read audit logs of authentication events for compliance and debugging
- Discover Hanko tenant configuration via the .well-known/config endpoint

## Use cases

### Passkey-First Sign-Up

Replace passwords with passkeys for new users by initiating POST /registration and advancing the returned flow_id through POST `/flow/{action}.` Hanko walks the client through WebAuthn credential creation and returns a JWT once the flow completes. The whole sign-up takes a few round trips and no password is ever stored.

Example prompt: Initiate a Hanko registration flow for email 'new@example.com' via POST /registration, then advance the returned flow_id through POST `/flow/submit_email.`

### Email OTP Fallback Login

When a user is on a device without a registered passkey, fall back to email OTP by initiating POST /login and using the flow state machine to send and verify a passcode. Hanko issues a JWT on success that the client stores and presents on subsequent API calls. The same /login endpoint handles passkey, OTP, and SSO branches without separate URLs.

Example prompt: Begin a login flow at POST /login for 'user@example.com', then call POST `/flow/send_passcode` and POST `/flow/verify_passcode` with the user's code.

### Admin User Management

Provision and offboard users from a back-office tool by calling `/admin/users` with an admin API key. Use POST `/admin/users` to add a user, GET `/admin/users` to list, GET `/admin/users/{user_id}` to inspect, and DELETE `/admin/users/{user_id}` to remove. The admin surface is separate from the end-user flow API and uses a different credential type.

Example prompt: Delete user with ID 'a1b2c3' via DELETE `/admin/users/a1b2c3` and confirm by listing users via GET `/admin/users.`

### AI Agent Identity Helper

Let an AI agent provision developer accounts for a sandbox environment by calling `/admin/users` through Jentic. The admin API key sits in your Jentic One instance and is injected as the Authorization header per call, so the agent context only sees a tool result. The agent cannot bypass passkey verification - that always happens client-side via WebAuthn.

Example prompt: When asked 'create a sandbox user for jane@example.com', call POST `/admin/users` with the email and return the new user_id.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/registration` | Initiate a registration flow |
| POST | `/login` | Initiate a login flow |
| POST | `/profile` | Initiate a profile management flow |
| POST | `/flow/{action}` | Advance a flow with a specific action |
| GET | `/.well-known/jwks.json` | Public JWKS for verifying issued JWTs |
| GET | `/admin/users` | List users (admin) |
| POST | `/admin/users` | Create a user (admin) |
| GET | `/admin/audit_logs` | List authentication audit logs |

## Key resources

- **Flows** — Registration, login, and profile flows driven through `/flow/{action}`
- **Admin Users** — Server-side user CRUD on `/admin/users`
- **Audit Logs** — Authentication event audit trail
- **Well-Known** — JWKS and tenant config discovery

## Why Jentic

- **Setup:** Wiring the Hanko API by hand means handling its two schemes, passing through end-user JWTs on the auth flows and setting the admin API key header only on the /admin endpoints, and building each registration, login, and flow request yourself. Through Jentic you install once, import the Hanko API from the API Directory, store the admin key once, and your agent calls it.
- **Permission scoping:** The Hanko API mixes public auth flows with admin management endpoints, so scope your agent to the operations it needs, such as starting a login flow or continuing it via `/flow/{action}.` You choose what it may call, so admin operations like creating or listing users and reading audit logs are not included unless you add them.
- **Credential handling:** Your Hanko admin API key is stored once, encrypted, by your own Jentic One instance and injected on the admin endpoints at execution time, while end-user JWTs pass through per request. Neither enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'start a passkey login flow', and Jentic returns the POST /login operation and its `/flow/{action}` continuation with their input schemas so the agent calls the right endpoint without crawling docs.hanko.io.

## Related APIs

- **Auth0** — Hosted identity platform with broader social SSO and enterprise federation, more complex flows.
- **Okta** — Enterprise identity with rich directory and lifecycle management features.
- **Stytch** — Passwordless and passkey API with similar developer ergonomics to Hanko.

## FAQ

### What authentication does the Hanko API use?

Hanko uses two schemes: end-user flows return a JWT bearer token verifiable against /.well-known/jwks.json, and admin endpoints require an API key in the Authorization header. Through Jentic the admin API key is stored encrypted in the vault and only injected for /admin/* calls.

### Can I sign up new users with passkeys via the Hanko API?

Yes. POST /registration starts a flow that walks the client through WebAuthn credential creation. Each step is advanced via POST `/flow/{action}` using the flow_id returned by the previous response, and a JWT is issued on completion.

### What are the rate limits for the Hanko API?

Hanko Cloud applies fair-use throttling per tenant; specific per-second limits are not published in the OpenAPI spec. The `/flow/{action}` endpoint enforces stricter limits per flow_id to prevent OTP brute-forcing. Build clients to back off on HTTP 429.

### How do I list users in my Hanko tenant through Jentic?

Search Jentic for 'list hanko users', load the schema for GET `/admin/users`, and execute. Jentic injects the admin API key as the Authorization header. Run pip install jentic and use the async client.search, client.load, and client.execute pattern.

### Does Hanko support social SSO providers like Google or Apple?

Hanko's flow-based API supports SSO branches alongside passkeys and email OTP, configured per tenant through the dashboard. The `/flow/{action}` endpoint advances the flow regardless of which method the user picked, so a single integration handles all enabled methods.

### Can I limit what my agent is allowed to do with the Hanko API?

Yes. Because you run Jentic One yourself, your own rules decide which Hanko operations and credentials the agent may use, so you can allow only the public auth flows it needs, such as starting a login with POST /login and continuing it through POST `/flow/{action}.` The admin management operations, like creating or listing users on `/admin/users` and reading `/admin/audit_logs`, are not available to the agent unless you explicitly add them. The admin API key stays in your instance and is injected only on the endpoints you have permitted, so the agent never gains reach beyond the operations you scoped.