Skip to main content

Setup

theauth.apiKeys is null unless the apiKeys key is passed to createTheAuth, so use theauth.apiKeys!. (or ?.) in your code.

Creating a key

The full key is never stored. Show it to the user immediately after creation, it cannot be recovered later. Only a SHA-256 hash is kept in the database.

Validating a key

validate returns null for an unknown or expired key and updates lastUsedAt on success. To check a permission in the same call, use validateWithScope. It returns null unless the key’s permissions include the required string or the * wildcard:
Permission strings are compared for exact equality (plus the literal *). There is no path matching here.

Listing and revoking

Rotating a key

Rotation deletes the existing key and creates a new one with the same name, permissions, and expiry date:
rotate throws if the key ID does not exist.

Endpoints

Add the apiKeys() plugin (from @glinr/theauth/auth) to expose HTTP endpoints. They act on the authenticated user, resolved from auth.adapter or an auth.session token, so a caller cannot manage another user’s keys.
The module’s own theauth.apiKeys.handleRequest serves similar paths but takes userId from the request body or path and does no authentication. Do not expose it directly to clients.

Agent identity

Bearer-token identities for autonomous agents, distinct from API keys.

Admin

User management tools including ban, impersonate, and delete.

Permissions

Attach scoped permissions to agents and keys.

Audit

Audit trail for agent activity.
Last modified on October 18, 2026