Identity & access

Refresh tokens, one-time codes and anonymous sign-in

Keeps users signed in, offers sign-in without a password, and lets a visitor try an application before creating an account.

BetaEngine edition 5f8ea3af

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

  • HTTPPOST /auth/v1/token?grant_type=refresh_token
  • HTTPPOST /auth/v1/otp, POST /auth/v1/verify, POST /auth/v1/recover
  • HTTPPOST /auth/v1/signup with a {} JSON body (anonymous)
  • HTTPPOST /auth/v1/logout
  • ConfigKYNETRA_OTP_HASH_PEPPERS
  • ConfigKYNETRA_SMTP_HOST, KYNETRA_SMTP_PORT, KYNETRA_SMTP_USER, KYNETRA_SMTP_PASS, KYNETRA_SMTP_FROM
  • ConfigKYNETRA_PUBLIC_URL

Example

Renew a session, then request a magic linkbash
# 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.