Official vendor OpenAPI document · agent-readyIdentity AuthAuthenticationbearer, apiKey11 EndpointsREST
For Agents
Run passkey, WebAuthn, and email OTP authentication flows and manage users and audit logs through a flow-based REST API.
Use for: Start a passkey registration flow for a new user, Begin a login flow for an existing Hanko user, Send an email OTP passcode for a user without a passkey, List all users in our Hanko tenant
Not supported: Does not handle SMS OTP delivery, payments, or session storage outside of JWT issuance - use for passkey, WebAuthn, and email OTP authentication flows only.
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.
Install Jentic One Beta
Connect the Hanko API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Hanko API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhanko.io%2Fhanko" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhanko.io%2Fhanko" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Hanko API.
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
Patterns agents use Hanko API for, with concrete tasks.
★ 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.
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.
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.
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.
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
11 endpoints — 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.
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
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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
H
Hanko API
- AI-Aware (B+)68/100
87
Foundational Compliance61
Developer Experience & Jentic Compatibility53
AI-Readiness & Agent Experience94
Agent Usability63
Security74
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
87
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: ASignals: 4
98%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
100%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
50%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
61
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: B-Signals: 4
0%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
45%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
53
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: C-Signals: 4
57%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
100%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
55%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
63
Security
Trust, risk posture, and security compliance.
Grade: B-Signals: 1
62%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
74
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A-Signals: 1
74%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Hanko API through Jentic.
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.
GET STARTED