Signet docs

Point the stock better-auth client at this instance’s API base path — that is the integration. These docs are embedded in the binary, so they are the same at 2am on an air-gapped host as they are anywhere else.

Quickstart

1. Write signet.toml with this instance's public origin and a Postgres DSN:

[server]
listen = "0.0.0.0:3000"
base_url = "https://auth.example.com"

[database]
adapter = "postgres"
dsn = "env:SIGNET_DATABASE_URL"

2. Provide the secret and database URL out-of-band, then boot (migrations run on start):

export SIGNET_SECRET="$(head -c 32 /dev/urandom | base64)"
export SIGNET_DATABASE_URL="postgres://user:pass@host/db"
signet            # add --config <path> to point elsewhere; --check validates and exits

3. Point any better-auth client at /api/auth on this origin. Confirm liveness at /health; browse the machine schema at /api/auth/open-api/generate-schema.

From your app

Any better-auth client integrates unchanged — point its baseURL at this instance. Plain JavaScript, no framework required:

import { createAuthClient } from "better-auth/client";

export const authClient = createAuthClient({
  baseURL: "https://auth.example.com/api/auth",
});

Sign a user up, then sign them in:

await authClient.signUp.email({ email, password, name });
await authClient.signIn.email({ email, password });

Read the current session, and sign out:

const { data } = await authClient.getSession();
await authClient.signOut();

CLI preflight

The production signet binary also owns setup and diagnostics; no second CLI package is installed:

signet init --database postgres --base-url https://auth.example.com
export SIGNET_SECRET="$(openssl rand -hex 32)"
export SIGNET_DATABASE_URL="postgres://user:pass@host/db"
signet doctor --offline
signet doctor
signet env pull --file .env.local

init writes a valid secret-free signet.toml and refuses an existing destination. Offline doctor checks config, licence posture, and delivery readiness; live doctor also drives /health and the generated OpenAPI schema, including its published server URL. env pull updates only SIGNET_AUTH_URL=https://auth.example.com/api/auth, preserves unrelated variables, and refuses duplicate assignments or symlink destinations. Use --stdout for one machine-clean assignment.

User metadata

Every user can carry three JSON objects. publicMetadata is readable by ordinary clients but writable only through an admin surface; privateMetadata is readable and writable only through admin surfaces; unsafeMetadata is browser-readable and browser-writable. Email sign-up and authenticated /api/auth/update-user therefore accept only unsafeMetadata. A request that tries to set either protected bucket is rejected rather than ignored.

await authClient.signUp.email({
  email,
  password,
  name,
  unsafeMetadata: { onboarding: { step: 1 } },
});

await fetch("https://auth.example.com/api/auth/update-user", {
  method: "POST",
  credentials: "include",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ unsafeMetadata: { onboarding: { step: 2 } } }),
});

Admin create/update accepts all three fields inside data. Each value replaces the whole bucket; send {} to clear it or omit it to leave it unchanged. Values must be objects, and the three encoded buckets share an 8192-byte limit. Private metadata is omitted from sign-up, sign-in, session, ordinary user, and session-JWT user shapes. Full contract: docs/user-metadata.md in the distribution.

Organization SSO domain ownership

Email/domain and organization-slug SSO discovery use only a provider whose exact normalized domain has passed a DNS TXT ownership proof. An organization-linked provider carries one domain; register another provider for another domain so a proof cannot cover an unproved comma-separated value.

Both proof routes take {"providerId":"acme-saml"} and require the managing user's session. For an organization provider, only an owner or admin may call them. The request returns a stable seven-day txtRecordName and txtRecordValue; publish the exact value, then verify. A domain can belong to only one verified provider. Signet re-resolves a seven-day-old proof and suspends discovery if the exact TXT value disappears. Sign-in selector precedence is explicit providerId, then organizationSlug, then domain or the domain part of email. Email discovery failures are intentionally uniform.

Password strength

[password] min_strength opts newly created passwords into zxcvbn score enforcement from 1 through 4. The default is 0 (disabled), preserving the length-only better-auth profile. Length checks still apply first.

A password-entry UI can request the exact instance decision and targeted feedback without storing or echoing the password:

const strength = await fetch("/api/auth/password-strength", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ password, userInputs: [email, name] }),
}).then(r => r.json());

// { score: 0..4, label, warning, suggestions, meetsPolicy, policy }

Resend a verification link

An expired verification link returns TOKEN_EXPIRED; malformed or altered input returns INVALID_TOKEN. Keep those callback codes intact so the landing page can explain the cause. Request a fresh one with the same better-auth client:

await authClient.sendVerificationEmail({
  email,
  // Replace "/" with your own notice-aware landing page when you have one.
  callbackURL: "/",
});

Without a client library, call the compatible endpoint directly:

curl -X POST "https://auth.example.com/api/auth/send-verification-email" \
  -H "content-type: application/json" \
  -H "origin: https://auth.example.com" \
  --data '{"email":"reader@example.com","callbackURL":"/"}'

Custom email templates

SMTP subjects and plain-text bodies can be overridden per flow under [delivery.smtp.templates]. Omitted fields keep Signet's built-in copy; values may be inline TOML or env:NAME / file:/path references.

[delivery.smtp.templates]
verification_email_subject = "Verify {{email}}"
verification_email_body = """
Open this link to verify {{email}}:

{{url}}
"""
password_reset_subject = "Reset your password"
password_reset_body = "file:/etc/signet/mail/password-reset.txt"

Placeholders are strict and flow-specific. Link bodies must contain {{url}}, OTP bodies {{otp}}, and invitation bodies {{invite_id}}; a typo or a template that omits its action value stops boot and names the field and fix. Common email variables are {{email}} and {{recipient}}. Link bodies also expose {{token}}; OTP exposes {{otp_type}}; invitations expose {{organization_name}} and {{inviter_email}}. Action secrets ({{otp}}, {{url}}, {{token}}, {{invite_id}}) are body-only so they do not leak into notification previews or subject logs. Subjects are one line and all bodies are text/plain. Signed-webhook delivery remains structured JSON because the receiving application already owns its final rendering.

Migrating from Clerk

Export all users from Clerk's Dashboard Settings → User Exports, then validate the complete file against this instance's configured PostgreSQL without writing:

signet import --config /etc/signet/signet.toml \
  --format clerk-csv --dry-run clerk-users.csv

Each line reports a row number, outcome, cause, and fix; each unconsumed Clerk column receives its own skip receipt. When failed=0, remove --dry-run. Re-running the same file is idempotent by normalized email.

signet import --config /etc/signet/signet.toml \
  --format clerk-csv clerk-users.csv

The intake preserves Clerk id as user.id, maps the primary address's membership in verified_email_addresses / unverified_email_addresses to user.emailVerified, and writes password_digest to a credential account. The original bcrypt password works immediately through /api/auth/sign-in/email. A successful login transparently replaces bcrypt, Argon2, PBKDF2-PHC, or scrypt-PHC with Signet's unchanged better-auth-native scrypt default.

For converted input, --format clerk-json accepts an array with the same CSV keys. Generic --format csv requires email, password_hash, and email_verified; optional columns are external_id, name, image, created_at, and updated_at.

API keys

API keys are user-owned credentials compatible with better-auth 1.6.23's default apiKey() plugin. Create, update, delete, and list require the owning user's session; verification is sessionless so an application backend can authenticate the presented key.

const created = await fetch("/api/auth/api-key/create", {
  method: "POST",
  headers: { "content-type": "application/json" },
  credentials: "include",
  body: JSON.stringify({ name: "deploy", prefix: "sk_prod_" }),
}).then(r => r.json());

// Send created.key to your secret store now. It is never returned again.
const result = await fetch("/api/auth/api-key/verify", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ key: process.env.SIGNET_API_KEY }),
}).then(r => r.json());

The full key is returned only by create. Signet stores a SHA-256 base64url digest; list, update, verify, and delete never expose the stored digest or the raw secret. Defaults match the reference: 64 random ASCII letters after the optional prefix, six identifying starting characters, no expiry, enabled, and a per-key verification limit of 10 requests per 24 hours. expiresIn is seconds; update with expiresIn: null removes expiry. An exhausted non-refillable key is deleted, and disabled, expired, exhausted, permission-denied, or rate-limited verification returns {valid:false,error,key:null}.

Agent authorization

An API key is a long-lived secret good at every door. An agent wants the opposite: a token that expires in minutes, names the API it may be presented to, and stops working the moment you revoke it. Two roads lead there. Road one rides the ordinary OAuth code flow and is in every build. Road two lets the customer’s own identity provider make the authorization decision, and is compiled in by --features external-jwt.

Road one — bind the token to the API it is for

Send RFC 8707 resource at /api/auth/oauth2/authorize or /api/auth/mcp/authorize, once per target the token is meant for:

GET /api/auth/oauth2/authorize?response_type=code&client_id=…&redirect_uri=…
    &code_challenge=…&code_challenge_method=S256
    &resource=https%3A%2F%2Fmcp.example.com%2F
    &resource=https%3A%2F%2Fcrm.example.com%2F

At most eight canonical absolute URIs per request; a ninth, or a duplicate, refuses. resource is the only parameter that may repeat — a repeated state, scope, client_id, or redirect_uri draws a 400 naming the field. An uncanonical value refuses at authorize with invalid_target, delivered to the registered redirect_uri, and mints no code. The whole set survives the login detour and the consent round-trip, and a refresh copies it from the row it rotates rather than from the request, so a refreshed token can neither widen its targets nor invent one.

Cut the token’s life down to one agent turn. A single key moves the OAuth and MCP doors together:

[oauth]
access_ttl_seconds = 900     # default 3600, accepted range 300-3600

Outside that range the instance refuses at boot and names the range. Five to thirty minutes (300–1800) is the agent profile: a leaked bearer stays useful for minutes rather than an hour, and the cost is one refresh round-trip per interval for clients holding offline_access.

The binding is enforced, not merely recorded. A token bound to one resource and presented at another does not quietly pass:

An unbound token — one whose flow never sent a resource — stays unrestricted, so a client that does not use resource indicators sees no change at all. But a caller that names an expected resource is told TOKEN_RESOURCE_UNBOUND rather than handed the token as unconfined. Revocation reaches the whole access family: POST /api/auth/oauth2/revoke kills an MCP access token as well as an OAuth one, and introspection and userinfo walk that same family, so one truth about a token holds at every door.

Road two — the enterprise makes the decision

This build carries the ID-JAG grant (Identity Assertion JWT Authorization Grant — the MCP Enterprise-Managed Agents profile). The customer’s own identity provider decides that this agent may reach this resource on this user’s behalf, and signs an assertion saying so. The agent presents the assertion at the token endpoint and receives an ordinary Signet access token. Nobody provisions a per-tenant credential out of band, because the assertion carries the decision — and its resource claim lands as the same binding road one writes, through the same canonicalizer and the same token writer.

Both discovery documents — /api/auth/.well-known/oauth-authorization-server and /api/auth/.well-known/openid-configuration — carry the grant in grant_types_supported, the profile in authorization_grant_profiles_supported, private_key_jwt in token_endpoint_auth_methods_supported, and client_id_metadata_document_supported. A build compiled without external-jwt publishes none of them and answers unsupported_grant_type at the token endpoint. The condition is the build, never a runtime switch, so no configuration can make this instance advertise a capability it does not carry.

Trust is configured, never discovered

The grant takes its key source from an ssoProvider row under the client’s organization. It never reads jku, x5u, or x5c from the assertion header, and never fetches what they name. The row carries providerId, issuer, organizationId, and an oidcConfig — a JSON string — naming the key set:

{"jwksEndpoint": "https://acme.okta.com/oauth2/v1/keys"}

Leave jwksEndpoint out and it hydrates from the issuer’s /.well-known/openid-configuration at redemption time, behind the same SSRF fence registration applies to a typed URL. issuer matches by RFC 3986 Simple String Comparison — equality, not normalization. The provider’s key may be RSA (RS256/RS384/RS512), EC (P-256→ES256, P-384→ES384), or OKP (EdDSA); the JWK’s key type decides the accepted algorithm, never the assertion’s own header, so an HMAC alg pointed at a public key set dies before verification.

Registering the agent’s client

A confidential client, inside the organization whose identity provider issues the assertion, registered for the grant. /api/auth/oauth2/create-client binds the client to the organization selected on the session cookie:

curl -X POST "https://auth.example.com/api/auth/oauth2/create-client" \
  -H 'content-type: application/json' \
  -H "cookie: $SESSION_COOKIE" \
  --data '{"redirect_uris": ["https://agent.acme.example/callback"],
           "grant_types": ["authorization_code",
                           "urn:ietf:params:oauth:grant-type:jwt-bearer"],
           "token_endpoint_auth_method": "private_key_jwt",
           "jwks": {"keys": [{"kty":"OKP","crv":"Ed25519","kid":"client-key-1","use":"sig","x":"…"}]}}'

The grant must sit on the row: the allow-list defaults closed, so a client registered before you added the URN is refused with unauthorized_client and told to register it. /api/auth/oauth2/update-client takes the same field. A private_key_jwt client gets no client_secret — its credential is a signature, and a shared secret beside the key would be a second, weaker way in that nothing rotates. Send exactly one key source, jwks by value or jwksUri by reference; neither, both, or a non-object jwks draws a named 400, and the one-source rule is judged over the merged row on update. An inline jwks costs no outbound request at token time.

What the assertion must carry

header   {"alg":"EdDSA","typ":"oauth-id-jag+jwt","kid":"idp-key"}
claims   {"iss":"https://acme.okta.com",          ← the registered provider's issuer, exactly
          "aud":"https://auth.example.com/api/auth",  ← this server's ISSUER IDENTIFIER, and only it
          "sub":"idp-subject-1",                  ← a user that already exists here
          "client_id":"…",                        ← the client authenticating this request
          "jti":"…", "iat":…, "exp":…,
          "scope":"openid profile",
          "resource":"https://mcp.example.com/"}  ← REQUIRED here, though ID-JAG marks it optional

typ must read oauth-id-jag+jwt: an ordinary identity-provider ID token is not a grant, and it fails on typ and on aud independently. aud must be exactly this server’s issuer identifier — one string, or an array of one; an array of two refuses even when one element is correct. exp carries 60 seconds of skew and must fall within an hour; nbf binds when present; jti and iat are required. client_id must name the authenticated client, so one client’s decision is not redeemable by another that happens to hold the assertion. scope narrows to the intersection with the client’s registered scopes, always minus offline_access — and an absent scope claim grants nothing, never the client’s defaults. Redeem it:

curl -X POST "https://auth.example.com/api/auth/oauth2/token" \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  -d assertion="$ID_JAG" \
  -d client_id="$CLIENT_ID" \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion="$CLIENT_ASSERTION"

The client assertion (RFC 7523 §2.2) carries iss and sub both equal to the client_id, a jti, an exp inside an hour, and an aud naming either this server’s issuer identifier or its token endpoint URL — the RFC admits both spellings and both authenticate here. A client holding a secret uses HTTP Basic instead; sending a secret and an assertion in one request refuses.

What comes back

{"access_token":"sig_at_…","token_type":"Bearer","expires_in":300,
 "expires_at":…,"scope":"openid profile","resource":["https://mcp.example.com/"]}

No refresh token, ever. The response body carries no such key — not a flag that happens to read false. Re-presenting the same assertion is the refresh mechanism, and it mints a fresh token every time. The token never outlives the decision that authorized it: its life is min(access_ttl_seconds, exp − now), measured against the stored assertion rather than the response. What comes back is an ordinary access credential — it introspects live at the resource the enterprise named and answers invalid_target anywhere else.

What road two refuses on purpose

Every assertion defect answers one byte-identical invalid_grant description, deliberately: a caller who can tell the checks apart holds a validator oracle, and ID-JAG §9.4 forbids disclosing which issuers a customer has registered. The server log names the check that refused, and every one of those lines states the limit and the corrective action. Four more conditions refuse for reasons worth knowing — an issuer registered twice inside one organization, an assertion whose iss is this server, an unknown form member, and a client-metadata URL that is http, loopback, private-network, cloud-metadata, path-less, or non-canonical. That last one refuses before any socket opens and reads exactly like “no such client”, because telling the two apart would map what this server will fetch.

Adopting a self-published client

A client that identified itself by publishing a document belongs to nobody, so it cannot speak for a tenant until an organization says it may. An owner or admin adopts it — an allow-list entry keyed on the exact URL, not a registration, and the client stays self-described:

curl -X POST "https://auth.example.com/api/auth/oauth2/adopt-client" \
  -H "content-type: application/json" -b "$SESSION_COOKIE" \
  -d '{"organizationId":"$ORG","clientId":"https://agent.example.com/client.json"}'

Signet fetches the document, records the RFC 7638 thumbprints of the keys it publishes today, and from then on the client resolves that organization’s tenant. If those keys ever differ, every redemption refuses until an owner or admin calls the same route again — the server will not accept a key nobody approved, and the cost of that is real: a client that rotates its keys has to be re-confirmed by each organization that adopted it. GET /api/auth/oauth2/client-adoptions?organizationId=… lists what an organization holds; POST /api/auth/oauth2/revoke-client-adoption withdraws one, keeping the row so it still records who authorized the agent and when.

More than one organization may adopt the same public agent, which is the ordinary case rather than an edge one. When several have, the tenant is the one whose identity provider issued the assertion and in which the assertion’s subject is already a member; if that is not exactly one organization, the redemption refuses rather than choosing.

Event webhooks

Configure [events] to receive user.created, account.locked, session.created, and session.revoked. Each JSON POST carries x-signet-timestamp (Unix seconds) and x-signet-signature (lowercase hex HMAC-SHA256). Verify the signature over the timestamp header, one ASCII dot, and the exact raw request body bytes:

events.secret must resolve to at least 32 characters. Generate one with openssl rand -hex 32, then provide it through an env: or file: reference.

signed_input = x-signet-timestamp + "." + raw_body
expected = hex(HMAC-SHA256(events.secret, signed_input))

Read and preserve the raw body before JSON decoding. Reject the request when abs(now_unix_seconds - x-signet-timestamp) > 300, then compare the supplied and expected signatures in constant time. A changed timestamp or body must fail verification.

session.revoked data contains id, userId, and reason. The reason enum is expired, sign_out, revoke_session, revoke_all, revoke_other_sessions, password_change, multi_session_revoke, session_replaced, two_factor_disabled, user_ban, admin_revoke_all, or admin_revoke. Bulk revocations emit one event per deleted session. Concurrent revokers use an atomic delete-and-return operation, so only the database winner emits for a session.

account.locked data contains canonical email, lockedUntil, lockLevel, and lastIp. The email may have no user row: unknown addresses accumulate identical lock state to preserve the sign-in enumeration posture.

Abuse controls

Production defaults combine the per-IP rate limiter with persistent per-email lockout, deny-first email admission rules, and a bundled disposable-domain snapshot. The compatibility harness explicitly disables these Signet extensions, so the certified better-auth response surface remains unchanged.

Persistent lockout

[lockout] defaults to five failures in ten minutes. The first lock lasts 15 minutes, doubles for each consecutive lock, and is capped at 24 hours; the escalation level decays after 24 clean hours. State is stored by canonical email string rather than user id, so failures for unknown and real addresses follow the same path across every process and IP. A locked sign-in returns 429 ACCOUNT_LOCKED with standard retry-after plus the existing Signet x-retry-after alias. A correct password never bypasses a lock.

Username/password sign-in checks both the account's email key and a reserved username alias key. Unknown usernames accrue the same alias state, preventing the username plugin from becoming either a lockout bypass or a threshold-based existence oracle.

A completed password reset clears the lock immediately. Operators can clear any canonical address (including one with no user row) with POST /admin/v1/users/unlock, body {"email":"user@example.com"}; the action writes user.unlock to the admin audit log.

Allowlist and blocklist

[email_policy] accepts only exact user@example.com, apex example.com, and *.example.com. A wildcard matches subdomains only, never the apex. Precedence is explicit block, then non-empty allowlist, then disposable blocking, so a block survives an allow typo and a deliberate allow entry can carve through the disposable list.

Every matcher uses one canonical form: surrounding whitespace and a trailing domain dot are removed, case is folded, domain Unicode becomes IDNA punycode, and a local plus-tag is stripped. Provider-specific dot folding is deliberately not attempted; Gmail-style dot aliases remain an operator-visible residual.

Disposable domains

[disposable_email] enabled defaults true for identity creation. The binary bundles snapshot 2026-07-23; a listed domain also catches every subdomain. extra_deny adds local domains and allow supplies carve-outs. list_path replaces the bundled snapshot with a local one-domain-per-line file; an unreadable or malformed file stops boot and names its file and line rather than silently failing open.

UI-kit boundary

Signet stays headless and does not ship signet-ui. React applications may use Better Auth UI through a stock better-auth browser client whose baseURL is this instance's full /api/auth auth path. The audited combination is better-auth 1.6.23 with @better-auth-ui/core, @better-auth-ui/react, and @better-auth-ui/heroui 1.6.43. Pin exact versions and regression-test application flows; third-party rendering, navigation, theming, and upgrades are application-owned.

Core email/password, social, reset/verification, session, profile, and account surfaces may use routes enabled by this instance. Enable a plugin component only when its complete endpoint set appears in /open-api/generate-schema or /llms-full.txt. A typed npm method does not prove that the deployed server implements it; Better Auth UI's passkey management, for example, calls list/add/delete methods this Signet build does not advertise.

JWT claim templates

The session-protected GET /api/auth/token keeps its better-auth-compatible public-user JWT when no query is supplied. Configure named [[jwt.templates]] allow-lists and request ?template=<name> when a relying party needs a different claim shape. Named tokens contain only configured claims plus server-owned iss, sub, iat, exp, and aud; audience is the sole registered-claim override.

Exact placeholders such as {{user.email}}, {{user.publicMetadata}}, and {{session.id}} preserve JSON types. Partial interpolation and unknown sources stop boot. Private metadata and session-token material have no placeholder. Each name, lifetime, claim size, nesting depth, duplicate, and protected claim is validated before the instance serves.

Step-up reverification

Sensitive routes return SESSION_NOT_FRESH when the current session is older than [session] fresh_age. GET /api/auth/reverify reports fresh, verifiedAt, freshUntil, a correlation ID, the required factor level, and available strategies. For a non-MFA credential account, POST /api/auth/reverify/password with {"password":"..."} verifies the real password and marks this session fresh.

When verified two-factor exists, password step-up returns SECOND_FACTOR_REQUIRED. Complete the existing authenticated /two-factor/verify-totp, delivered send-otp + verify-otp, or single-use verify-backup-code route. A passkey assertion through the existing authentication ceremony rotates to a new fresh session. Five failed password or TOTP submissions in ten minutes produce a ten-minute session-bound REVERIFICATION_LOCKED with retry-after; delivered OTP retains its own five-attempt code budget.

End-to-end test sessions

The private, repository-owned @signet/testing package signs a fixture account in through the ordinary POST /api/auth/sign-in/email route, reads the signed credential exposed by the bearer plugin, and installs the real better-auth.session_token cookie for Playwright or Cypress. API tests can send the same credential as Authorization: Bearer. The package is path/workspace-installable from packages/signet-testing and is not published to npm.

Bot protection at the edge

Signet does not contain bot scoring, browser fingerprinting, CAPTCHA, or a Clerk-style bot-detection switch. A public deployment should put WAF and rate controls at its trusted edge while retaining Signet's built-in per-IP/path rate limiter, persistent identity lockout, and email-admission policy.

For a Cloudflare-fronted origin, prevent direct-origin access and have the last trusted proxy replace X-Forwarded-For with the single CF-Connecting-IP value received from Cloudflare. Signet keys its limiter from the first forwarded value; appending a client-supplied chain gives the client control over its bucket.

Scope edge rules to the exact hostname, method, and configured /api/auth routes. Browser challenges are not transparent to better-auth JSON, mobile, callback, or monitoring clients. Cloudflare Bot Fight Mode covers the whole domain and cannot be skipped by custom WAF rules, so it is not a safe default for an auth/API hostname. Turnstile is not integrated; a widget alone does not protect the direct JSON routes and any custom use requires server-side validation.

Signet configuration reference

Rate limits

Per-client rate limiting is on by default ([rate_limit] enabled defaults true). Each client is keyed by source IP and request path; exceeding a limit returns 429 with an x-retry-after header carrying the seconds until the window resets.

Tune the default with [rate_limit] window and max, or override any path with a [[rate_limit.rules]] block (exact path or a * wildcard). Custom rules take precedence over the built-in per-path limits above, which in turn override the default.

storage = "memory" is the default and keeps counters inside one process. Set storage = "database" with the PostgreSQL adapter to coordinate one atomic quota across every Signet process sharing that schema; migration 0002_rate_limit.sql creates the table. Database failures return a generic 500 rather than letting requests bypass the limiter.

Social sign-in providers

Add one [[social_providers]] block per OAuth/OIDC provider. google and github carry built-in endpoint, scope, and PKCE defaults; any other OIDC-compatible provider works by supplying its endpoints yourself.

A worked example — Google, with the secret kept in the environment:

[[social_providers]]
id                     = "google"
client_id              = "env:GOOGLE_CLIENT_ID"
client_secret          = "env:GOOGLE_CLIENT_SECRET"
authorization_endpoint = "https://accounts.google.com/o/oauth2/v2/auth"
token_endpoint         = "https://oauth2.googleapis.com/token"
scopes                 = ["email", "profile", "openid"]
pkce                   = true

Because google ships those defaults, the endpoint, scope, and PKCE lines above are optional — id, client_id, and client_secret alone are enough. A custom provider supplies its own authorization_endpoint, token_endpoint, and user_endpoint.

Operating the instance

Signet's only bespoke data command is the direct-database import intake documented above. Lifecycle operations use your own PostgreSQL and standard tooling, because your data is yours — that is the sovereignty guarantee, not a feature to buy back.

Upgrade

Replace the binary and restart the process. Embedded migrations run automatically on boot whenever [database] migrate is true (the default), so the schema moves forward with the binary. Users, sessions, and accounts live in PostgreSQL, so they survive the swap; a graceful shutdown (SIGTERM / Ctrl‑C) lets in-flight requests finish first. Validate the new build against your config before cutting over:

signet --config /etc/signet/signet.toml --check   # prints "config OK" and exits
# then swap the binary and restart the service

Backup

All durable state is in the PostgreSQL database named by [database] dsn. Back it up with pg_dump; there is no separate Signet backup command to run or trust.

pg_dump "$SIGNET_DATABASE_URL" --format=custom --file signet-$(date +%F).dump

Restore

Restore the dump into a database, point [database] dsn at it, and boot. Migrations are idempotent: already-applied ones are skipped, so a restored database that is already at the current schema needs no extra step.

pg_restore --clean --if-exists --dbname "$SIGNET_DATABASE_URL" signet-2026-01-01.dump
signet --config /etc/signet/signet.toml   # migrations reconcile on boot

Export

The binary ships no export subcommand, and none is needed: your data never leaves your PostgreSQL. Use pg_dump for a complete restorable archive. For a portable handoff, export both users and accounts — password hashes live in account.password, not in user.

umask 077
pg_dump "$SIGNET_DATABASE_URL" --format=custom --file signet.dump

psql "$SIGNET_DATABASE_URL" --csv -c '
  SELECT "id", "name", "email", "emailVerified", "image", "createdAt", "updatedAt"
  FROM "user" ORDER BY "createdAt", "id"
' > signet-users.csv

psql "$SIGNET_DATABASE_URL" --csv -c '
  SELECT "id", "userId", "accountId", "providerId", "password",
         "accessToken", "refreshToken", "idToken", "scope", "createdAt", "updatedAt"
  FROM "account" ORDER BY "userId", "providerId", "id"
' > signet-accounts.csv

A joined export uses FROM "user" AS u LEFT JOIN "account" AS a ON a."userId" = u."id"; keep the left join so passwordless/social-only users remain visible. Count user, all account rows, and credential accounts before and after migration. Treat every file as credential material: password hashes and OAuth tokens require restrictive permissions, encryption at rest, and authenticated transfer.

Certification & support

This instance's compatibility receipt: /certification (JSON). Machine on-ramp for AI agents: /llms.txt.