What it does
Rotating refresh tokens renew access tokens without a password. Six-digit codes and magic links, delivered by email, support passwordless sign-in, email confirmation and password recovery. Anonymous sign-in creates a viewer account with no password. Delivery and hashing depend on configuration the deployment must supply.
How it works
A refresh token is 32 random bytes written as URL-safe text. Just its SHA-256 hash is stored, with the user, the issue and expiry times and a revoked flag. Exchanging a refresh token marks it revoked and returns a new access token and a new refresh token, so each token works once. A revoked or expired token is refused, and signing out revokes all of a user's refresh tokens. In the platform pool each refresh token is also bound to the session context it was issued under, and renewal is refused if that context has changed.
A code request produces a six-digit code and a longer link token. Both are valid for 15 minutes and usable once. They are stored as keyed HMAC-SHA-256 hashes bound to the address, the purpose (magic link, recovery or sign-up) and a per-request challenge id; the raw values are present in the email and nowhere else. Redeeming a code or link for the magic-link or sign-up purpose marks the address verified, and redeeming for recovery can set a new password in the same call. The response is an empty JSON object whether or not the address is known.
Anonymous sign-in is a sign-up request with no email and no password. It creates a record with the viewer role, marked anonymous, and returns the same token pair as any other sign-in.
A platform account that has MFA enabled, or whose organisation requires it, receives a challenge instead of tokens when it redeems a code, and finishes through the MFA step.
Where you reach it
- HTTP
POST /auth/v1/token?grant_type=refresh_token - HTTP
POST /auth/v1/otp, POST /auth/v1/verify, POST /auth/v1/recover - HTTP
POST /auth/v1/signup with a {} JSON body (anonymous) - HTTP
POST /auth/v1/logout - Config
KYNETRA_OTP_HASH_PEPPERS - Config
KYNETRA_SMTP_HOST, KYNETRA_SMTP_PORT, KYNETRA_SMTP_USER, KYNETRA_SMTP_PASS, KYNETRA_SMTP_FROM - Config
KYNETRA_PUBLIC_URL
Example
# Exchange a refresh token for a new access token and a new refresh token
curl -s -X POST "$KYNETRA_URL/auth/v1/token?grant_type=refresh_token" \
-H "apikey: $PROJECT_ANON_KEY" \
-H "Content-Type: application/json" \
-d '{"refresh_token":"<refresh_token>"}'
# Ask for a six-digit code and a magic link by email (the response is an empty object)
curl -s -X POST "$KYNETRA_URL/auth/v1/otp" \
-H "apikey: $PROJECT_ANON_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"ada@example.com","type":"magiclink"}'Limits
- One-time codes need a keyed hashing configuration. Set KYNETRA_OTP_HASH_PEPPERS to an active key id and key, plus any older keys that must still verify. Without it, code requests fail with a server error.
- Email is sent over SMTP. The built-in client does not use TLS, so the message and any SMTP credentials travel unencrypted. Point it at a relay on the same host or inside a private network. With no SMTP host configured, the message, including the code and link, is written to the server log instead of being sent.
- A code request for an address that has no account creates a passwordless account record for it, with the viewer role. In an empty pool the first such account becomes admin.
- Anonymous accounts and expired token and code records are not purged automatically in this release, so each anonymous sign-in leaves a stored account behind.
- Refresh tokens are looked up by scanning the stored token records. No throughput figure is published for this edition.
- KYNETRA_PUBLIC_URL sets the base address used in links. It defaults to a local address.
Evidence
- On this siteAPI reference: authentication endpoints
- Tests8 session and code tests in the auth crate (rotation revokes the old token, revoked token refused, raw values not stored, one-time use, wrong purpose, anonymous sign-up) and 18 keyed-hash tests for one-time codes
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to talk through the limits above against your own workload.