Docs · the operator contract

The Admin API.

The official contract for the operator surface of a Signet instance (/admin/v1): 46 operations across users, sessions, tokens, delivery and event dead-letters, configuration, audit and stats. Pinned at tag signetctl-v0.1.0.

stats users app-users sessions api-keys service-principals authorization-roles principal-role-grants service-tokens signing-keys platform-credentials tokens deliveries events config audit

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 surface; 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.

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

service-principals

Operation	Route	What it does
`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 Ed25519 JWKS 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

platform-credentials

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

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_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

Absent by design, recorded rather than forgotten: organisations, API keys and OAuth2 clients have no operator-key surface today. When the engine ships one, it is added to the contract first, then the CLI grows the verb. The surface mounts only when an admin key is configured; without one, every path answers 404.