# Signet — machine on-ramp (developer site)
# https://signetauth.dev

Signet is the identity plane for people, services, and agents. Every user, session, and secret lives in your own PostgreSQL, hosted by the Signet team or, under an enterprise licence, on your own metal; it needs nothing from the public internet. Point a stock better-auth client at a Signet instance and the calls you already write keep working (certification gap 0; scoped to the checks in the public compatibility profile, not a claim that every better-auth route is implemented).

## Developer sections
https://signetauth.dev/quickstart Start: Get a signed-in user today.
https://signetauth.dev/docs Guides: SSO, agents, limits, erasing a user.
https://signetauth.dev/reference Reference: Every route and setting, generated.
https://signetauth.dev/admin-api Admin and CLI: The operator API and command line.
https://signetauth.dev/changelog Changelog: What changed, and what you must do.
https://signetauth.dev/reference/routes The generated route list, readable without an instance to hand.
https://signetauth.dev/configuration Every signet.toml setting.
https://signetauth.dev/docs/cli Using the command line.
https://signetauth.dev/docs/security-disclosure Reporting a vulnerability.
https://signetauth.dev/admin-api The operator API.
https://signetauth.dev/signetctl The command line reference, generated from the signetctl binary at engine commit 06bcd58690ed.

## Integration facts
Instance reference: {instance}/api/auth/reference
Admin API contract: 64 operations, source commit 06bcd58690ed.
Pinned client: better-auth 1.6.23

## Recorded compatibility facts
Compatibility profile: better-auth 1.6.23
Certification gap: 0
Scope: The compatibility profile is a public, replayable set of checks; the same checks run against the better-auth reference implementation and against Signet, and the gap is the count of checks the reference passes and Signet does not. Gap 0 means that on every check in the profile, a client cannot tell the two apart. It is not a claim that every better-auth route is implemented: the profile is scoped to what those checks exercise, and anything they do not exercise sits outside it. Ask about a specific route and we will tell you plainly whether it is in the profile.
Conformance sweep: 280 / 280
End-to-end acceptance: 14 / 14
Recorded: 2026-07-22

These figures describe the named compatibility profile. They do not claim that
every better-auth route or plugin is implemented.

## Capability ledger
What the engine does today. Rule: built and driven = listed; partial or
unproven = explicitly scoped or absent. The embedded /docs of a live instance
(e.g. https://signetauth.dev/reference/routes) is the reference this list must agree with.
- Email + password — built. Sign-up, sign-in, password policy, breached-password check, reset.
- Magic links — built; sign-in proven in a real browser.
- Email OTP — built. Sign-in, email verification, password reset, email change.
- Passkeys (WebAuthn): built. Real ceremony crypto and soft-authenticator tests.
- Two-factor — built. TOTP, emailed OTP second factor, single-use backup codes;
  lost-authenticator recovery driven in a browser end to end.
- Social sign-in — built. Sign in with, link, unlink.
- Organisations + invitations: built. The /organization/* routes (create, invite, members, roles, and the rest).
- API keys: built. The /api-key/* routes.
- Device-code flow: built. The /device/* routes.
- MCP auth: built. The /mcp/* routes; agents are first-class clients.
- Agent tokens (audience-bound) — built. One config key sets access-token life
  from five minutes to an hour; the token names up to eight APIs it may be
  presented to (RFC 8707 resource); scope is what the signed-in person approved,
  intersected with what the client registered; revoke kills an MCP access token,
  not only an OAuth one; introspection, userinfo and revoke read one credential
  family. The OAuth and MCP doors read the same key and the same binding. A token
  that named no resource stays unrestricted. In every build, no feature flag.
- Session + token inventory and revocation — built.
- OAuth2/OIDC provider — BUILT: authorization-code + PKCE, refresh with reuse
  detection and client credentials, plus discovery, JWKS, userinfo, introspection,
  revocation and dynamic client registration. ID-token signing supports EdDSA and RS256.
  The client's stored id_token_signed_response_alg selects an available active signing
  algorithm; discovery lists the available algorithms with the default first. New installs
  default omissions to RS256; migrated installs with an existing signing key remain
  explicitly EdDSA. This does not claim complete OIDC Core conformance.
- Enterprise SSO (SAML + OIDC) — SCOPED: the OIDC transport is driven against a
  LIVE Microsoft Entra tenant (real sign-in with MFA, tenant-pinned token
  exchange, callback-time org provisioning). SAML completes full round trips
  against a conformance IdP but has no commercial-IdP drive yet, so the row is
  scoped to the transport that has one.
- Enterprise-managed agents (EMA / ID-JAG) — SCOPED: the engine accepts a signed
  authorization decision from the identity provider the customer already runs and
  mints a matching token, with no per-tenant shared secret. The grant must name
  the API, the identity provider must already be registered against that
  organization, the person must hold a live seat, scope is the grant's scope cut
  to the client's registration, the token cannot outlive the grant, and no refresh
  token is issued. Built to the finished MCP profile (final 2026-07-28) and driven
  against a signing identity provider we run ourselves; a capture from a live
  commercial tenant is not yet recorded, and not claimed.
Absent from this list is absent from the product today.

## Machine identity and delegated administration

Every credential speaks for one typed subject. Signet distinguishes people from services and
from application end-users, rather than assuming a human behind every credential.

- **Service credentials are organization property.** A service identity is created once and
  outlives any individual credential issued for it. Credentials can be minted, introspected,
  and revoked — individually, or every credential belonging to one identity at once.
- **Tenant binding is written at issue time.** A credential's organization is recorded when it
  is minted; it is never derived from request input, so no request can widen it.
- **Named roles, defined per tenant.** An organization defines its own roles as exact
  enumerated permissions — no wildcards. A credential's effective authority is its declared
  permissions intersected with what its identity has actually been granted, never the union,
  and it is re-derived from live grants on every request. Revoking a grant narrows credentials
  that were already issued.
- **Delegated tenant administration.** An organization can hold an administrative credential
  scoped to itself, and use it to create identities, roles, grants and credentials without ever
  holding an instance-wide key. A delegated credential can never grant authority it does not
  itself hold, and authority cannot increase along a delegation chain.
- **Sub-tenant scoping.** A credential can be bound to an exact workspace path. Requests
  presenting the wrong workspace, no workspace, or a workspace on an unbound credential are
  each refused distinctly.
- **Batch issuance with durable receipts.** A whole estate of service credentials can be minted
  from one manifest, idempotently: replaying the same manifest returns the same result rather
  than issuing duplicates, and a manifest containing any ineligible entry issues nothing at all.
- **Standards.** Credential introspection follows RFC 7662.

Cross-tenant requests are refused with responses that disclose nothing about whether the named
target exists.

Vocabulary, for readers of the Admin API and signetctl: a service credential is a
service token, and every typed subject (person, service, application end-user) is a
principal.

## Client integration contract
Certified better-auth package version: 1.6.23
Default auth base path: /api/auth
Install: npm i better-auth (or bun add better-auth)
No Signet SDK is required. The ADK (AI Development Kit) — the machine surfaces
this file belongs to, the instance's version-matched /llms.txt and
/llms-full.txt, /open-api/generate-schema, /certification.json, and the
quickstarts — is the agent on-ramp Signet serves instead of a library.
The ADK also has an executable form since signetctl v0.1.0: signetctl agent
(BYO OpenAI-compatible endpoint only, no default LLM, no telemetry; TUI REPL,
headless -p, --output-format stream-json for driving it as a subprocess) and
signetctl mcp serve (stateless MCP per the 2026-07-28 revision, with durable
tasks). The operator surface itself is documented as a repo contract —
https://signetauth.dev/admin-api, 64 operations, operationIds bound 1:1 to signetctl verbs by
a build gate. Instances do not serve that document; they serve only the
auth-wire OpenAPI.

Migration facts (from the rehearsed cutover runbook): moving off self-hosted
better-auth copies user rows, password hashes and live sessions as they are —
nobody resets a password and signed-in users stay signed in; rollback keeps
pre-cutover sessions valid. Moving off another vendor: exported password
hashes import (argon2, bcrypt, PBKDF2, scrypt); sessions do not transfer.

Browser clients should call /api/auth on their own origin. When the app and the
Signet instance use different origins, put a same-origin server gateway in
front of the instance: forward method, query, body, Cookie, and Origin;
preserve every Set-Cookie header separately; remove any upstream Domain attribute so the
browser binds the cookie to the application origin. Add the application origin
to the instance's [server].trusted_origins. The runnable Next.js starter below
implements and smoke-tests that boundary.

Server APIs can verify a caller by creating the stock better-auth/client with
the instance /api/auth URL and calling getSession with the incoming Cookie
header. The Express starter implements and smoke-tests that boundary.

## Five framework quickstarts
1. Next.js App Router — better-auth/react; client component plus same-origin route handler.
2. React Router v7 — better-auth/react in components; better-auth/client in loaders.
3. Node / Express — better-auth/client; getSession with forwarded request cookies.
4. Vue 3 — better-auth/vue; useSession returns Vue reactive state.
5. Svelte — better-auth/svelte; useSession returns a Svelte-readable nanostore.

Supplemental foundations on https://signetauth.dev/quickstart:
- React SPA client — better-auth/react.
- Plain JavaScript — better-auth/client.

## Runnable starters
The Next.js starter ships with your Signet delivery at examples/starters/next-app
(hosted onboarding or the enterprise source delivery); there is no public download.
Purpose: complete Next.js App Router sign-up/sign-in UI and /api/auth gateway.
Run: npm ci && npm test
Configure: copy .env.example to .env.local and set SIGNET_URL to an absolute
           URL ending in /api/auth. No engine secret belongs in this app.

The Express starter ships in the same delivery at examples/starters/express-api.
Purpose: Express /api/me resource guard using the stock client and caller cookie.
Run: npm ci && npm test
Configure: set SIGNET_URL to an absolute URL ending in /api/auth.

Both tests create a local Signet-shaped stub and drive the real HTTP boundary;
they require no live account, committed secret, or database.

## Configuration on-ramp
Human mapping: https://signetauth.dev/configuration
Per-instance generated reference: GET /docs on the deployed instance.
Real top-level sections demonstrated on the mapping page include [server],
[database], [delivery.smtp.templates], [session], [password], [rate_limit],
[[rate_limit.rules]], [lockout], [email_policy], [disposable_email],
[[social_providers]], [plugins], [events], [admin_plugin], and [admin]. The
per-instance /docs reference, not this list, is authoritative for accepted keys.

## Per-instance machine authorities
GET /llms.txt                     terse profile and enabled endpoint list
GET /llms-full.txt                deep flow-grouped integration reference
GET /open-api/generate-schema     OpenAPI 3.1.1 document under the auth base path
GET /certification.json           machine-readable compatibility receipt
GET /docs                         human quickstart plus generated config reference

Integrate against your deployed instance. Its schema is authoritative for its route inventory.