Two authorities, deliberately separate. A running instance serves the auth-wire OpenAPI at /api/auth/open-api/generate-schema, and that document covers the better-auth wire only. This contract lives in the repository and covers the operator API; instances do not serve it.
The names are load-bearing. Every
operationId equals a
signetctl command path:
users_list is
signetctl users list. A build gate asserts the bijection in both directions, so the contract and the CLI cannot drift apart. The
signetctl reference is the same list wearing its terminal form.
grants
| Operation | Route | What it does |
|---|
grants_create | POST /admin/v1/grants | Create one exact opaque principal/resource/capability grant (grants:write) |
grants_list | GET /admin/v1/grants | List grants in the caller's tenant scope (grants:read) |
grants_check | GET /admin/v1/grants/check | Check one exact opaque principal/resource/capability tuple (grants:read) |
grants_get | GET /admin/v1/grants/{id} | Fetch one grant in the caller's tenant scope (grants:read) |
grants_revoke | DELETE /admin/v1/grants/{id} | Idempotently revoke one grant in the caller's tenant scope (grants:write) |
grants_revoke_many | POST /admin/v1/grants/revoke | Revoke every live grant matching exact filters (grants:write) |
stats
| Operation | Route | What it does |
|---|
stats | GET /admin/v1/stats | Instance stats: users, active sessions, sign-ins per day, delivery and rate-limit counters |
users
| Operation | Route | What it does |
|---|
users_list | GET /admin/v1/users | List users, newest first, with case-insensitive substring search over email and name |
users_create | POST /admin/v1/users | Create a user (optionally with password, role, and profile data) |
users_set_role | POST /admin/v1/users/{id}/role | Set a user's role or roles |
users_delete | DELETE /admin/v1/users/{id} | IRREVERSIBLE: delete a user and every row they own |
users_ban | POST /admin/v1/users/{id}/ban | Ban a user (reversible): revokes their sessions and user-backed credentials |
users_unban | POST /admin/v1/users/{id}/unban | Lift a user's ban |
users_unlock | POST /admin/v1/users/unlock | Clear a lockout/escalation state, addressed by email (not id) |
users_sessions | GET /admin/v1/users/{id}/sessions | List a user's sessions |
users_revoke_all | POST /admin/v1/users/{id}/revoke-all | Revoke every session belonging to a user |
app-users
| Operation | Route | What it does |
|---|
app_users_list | GET /admin/v1/app-users | List one canonical application's end-user population, newest first |
app_users_create | POST /admin/v1/app-users | Create one tenant/application-scoped end user |
app_users_delete | DELETE /admin/v1/app-users/{id} | IRREVERSIBLE: erase one app_user principal and its sessions |
sessions
| Operation | Route | What it does |
|---|
sessions_revoke | POST /admin/v1/sessions/{token}/revoke | Revoke one session by its at-rest token reference |
api-keys
| Operation | Route | What it does |
|---|
api_keys_mint | POST /admin/v1/api-keys | Mint a declared-permission API key for an existing user |
ssh-machine-issuers
| Operation | Route | What it does |
|---|
ssh_machine_issuers_register | POST /admin/v1/ssh-machine-issuers | Register a trusted machine SSH task issuer in the infrastructure organization |
service-principals
| Operation | Route | What it does |
|---|
service_principals_ssh_machine_template_register | POST /admin/v1/service-principals/{id}/ssh-machine-templates | Bind one machine SSH task template to a live service principal |
service_principals_list | GET /admin/v1/service-principals | Service identities, keyset-paged (cursor, not offset) and filterable by organization |
service_principals_create | POST /admin/v1/service-principals | Create a stable tenant-owned service identity with a server-generated id |
service_principals_get | GET /admin/v1/service-principals/{id} | One service identity with its role grants and each credential's engine-computed ceiling |
service_principals_delete | DELETE /admin/v1/service-principals/{id} | Delete one disarmed service principal after all credentials and open batches are terminal |
authorization-roles
| Operation | Route | What it does |
|---|
authorization_roles_list | GET /admin/v1/authorization-roles | Persisted D150 roles, keyset-paged and filterable by organization |
authorization_roles_create | POST /admin/v1/authorization-roles | Create an immutable named D150 permission bundle in one exact scope |
principal-role-grants
| Operation | Route | What it does |
|---|
principal_role_grants_list | GET /admin/v1/principal-role-grants | Which identities hold which roles, keyset-paged and filterable by principal and/or role |
principal_role_grants_create | POST /admin/v1/principal-role-grants | Grant one existing scoped authorization role to one existing principal |
service-tokens
| Operation | Route | What it does |
|---|
service_tokens_mint | POST /admin/v1/service-tokens | Mint a required-expiry credential for an existing service principal |
service_tokens_rotate | POST /admin/v1/service-tokens/{id}/rotate | Rotate one active service token with an explicit bounded overlap |
service_tokens_mint_batch | POST /admin/v1/service-token-batches | Idempotently mint one pre-provisioned tenant credential manifest |
service_tokens_reconcile_batch | POST /admin/v1/service-token-batches/{id}/reconcile | Abandon one crashed U13 claim and revoke every reverse-linked destination token |
service_tokens_remint_batch | POST /admin/v1/service-token-remints | Prevalidate and remint one complete U6 legacy-credential batch |
signing-keys
| Operation | Route | What it does |
|---|
signing_keys_list | GET /admin/v1/signing-keys | List Ed25519 JWKS signing-key lifecycle metadata |
signing_keys_prepare | POST /admin/v1/signing-keys/prepare | Prepare one EdDSA or RS256 JWKS-lane successor |
signing_keys_activate | POST /admin/v1/signing-keys/{kid}/activate | Activate a dwelled prepared JWKS successor |
signing_keys_revoke | POST /admin/v1/signing-keys/{handle}/revoke | Revoke a prepared, retiring, or emergency active JWKS key |
| Operation | Route | What it does |
|---|
platform_credentials_list | GET /admin/v1/platform-credentials | List durable platform-administrator credential lifecycle metadata |
platform_credentials_rotate | POST /admin/v1/platform-credentials/rotate | Mint a managed platform credential with bounded predecessor overlap |
platform_credentials_revoke | POST /admin/v1/platform-credentials/{id}/revoke | Revoke one retiring or offline-recovery platform credential |
tokens
| Operation | Route | What it does |
|---|
tokens_list | GET /admin/v1/tokens | Token inventory, keyset-paged (cursor, not offset) |
tokens_config | GET /admin/v1/tokens/config | The token-kind registry (read-only) |
tokens_get | GET /admin/v1/tokens/{id} | One token record by handle |
tokens_revoke | POST /admin/v1/tokens/{id}/revoke | Revoke one exact token handle |
tokens_revoke_principal | POST /admin/v1/principals/{id}/tokens/revoke | Review then atomically revoke one service principal's exact active credential estate |
messages
| Operation | Route | What it does |
|---|
messages_hobby_waitlist | POST /admin/v1/messages/hobby-waitlist | Send one numbered Hobby waitlist stage mail |
deliveries
| Operation | Route | What it does |
|---|
deliveries_dead_letters | GET /admin/v1/deliveries/dead-letters | List delivery dead-letters (undeliverable emails/webhooks) |
deliveries_replay | POST /admin/v1/deliveries/dead-letters/{id}/replay | Replay one dead-lettered delivery |
events
| Operation | Route | What it does |
|---|
events_dead_letters | GET /admin/v1/events/dead-letters | List event dead-letters |
events_deliveries | GET /admin/v1/events/deliveries | List durable event-delivery retry state and terminal rollup receipts |
events_replay | POST /admin/v1/events/dead-letters/{id}/replay | Replay one dead-lettered event |
config
| Operation | Route | What it does |
|---|
config_show | GET /admin/v1/config | Configuration introspection: secrets absent by construction, never masked |
audit
| Operation | Route | What it does |
|---|
audit_export | GET /admin/v1/audit/export | Export the admin audit log as NDJSON |
vault
| Operation | Route | What it does |
|---|
vault_list | GET /admin/v1/vault | List an organization's secret paths and metadata: never a value |
vault_get | GET /admin/v1/vault/{path} | Decrypt and return one secret: receipted before the value is returned |
vault_put | PUT /admin/v1/vault/{path} | Create a secret or write a new version, shredding the one it supersedes |
vault_rotate | POST /admin/v1/vault/{path}/rotate | Write a new version under a fresh data key and crypto-shred the previous one |
vault_revoke | POST /admin/v1/vault/{path}/revoke | Withdraw a secret by deleting its data key: the ciphertext becomes unrecoverable |
vault_unseal | POST /admin/v1/vault-master-key | Supply this instance's 32-byte vault master key, the only supported way one arrives |
vault_status | GET /admin/v1/vault-status | Report the vault seal state, memory hygiene posture, and the corrective action |
vault_audit_export | GET /admin/v1/vault-audit-export | Export the vault's hash-chained receipt trail as NDJSON: every read, write and refusal |
Absent by design, recorded rather than forgotten: organizations and OAuth2 clients have no operator-key API today. When Signet ships one, it is added to the contract first, then the CLI grows the verb. The API mounts only when an admin key is configured; without one, every path answers 404.