Users API

List this product's API keys, newest first — id, label, type, visible prefix and revocation state. A server key's secret is never here; a publishable key's full value is, because it is not a secret.

MCP tool: users_apikeys_list

Parameters

No parameters.

Response

Issue an API key for this product. type='server' mints a secret backend key (usk_…) returned EXACTLY ONCE — it authenticates the code-exchange leg and is stored only as a hash, so a lost key must be replaced, never recovered. type='publishable' mints a non-secret browser key (upk_…) that only names this product and stays readable afterwards.

MCP tool: users_apikeys_create

Parameters

Response

Revoke an API key immediately. A revoked server key stops authenticating code exchanges on the next request; there is no grace period and no un-revoke.

MCP tool: users_apikeys_revoke

Parameters

Response

Read this product's audit log, newest first. Every management-plane mutation writes one entry (user.created, user.updated, user.deleted, user.banned, user.unbanned) with the actor, target and timestamp. Filter by action, target and time range; paginate with the opaque `nextCursor`.

MCP tool: users_audit_list

Parameters

Response

Read this product's end-user auth configuration (signup mode, password policy, session lifetime). Returns the defaults when nothing has been configured yet.

MCP tool: users_config_get

Parameters

No parameters.

Response

Create or update this product's end-user auth configuration. Only the fields you pass change; the rest keep their current values. Rejected while the product is paused (archived or blocked by the platform).

MCP tool: users_config_upsert

Parameters

Response

List this product's JWT signing keys, newest first: the key id (the `kid` a token header carries), its lifecycle state, and when it was created, retired and revoked. `current` signs; `retired` no longer signs but is STILL published in JWKS until `overlapExpiresAt`, so tokens it signed keep verifying; `standby` is the pre-generated successor and is not published; `revoked` was evicted from JWKS immediately. Key material — public or private — is never returned here.

MCP tool: users_keys_list

Parameters

No parameters.

Response

THE KEY-COMPROMISE DRILL. Evict a signing key from the published JWKS IMMEDIATELY — no overlap, no grace — so every token it ever signed stops verifying at once, mint or promote a fresh signing key in its place, and (by default) sign every end user of this product out, because a token the attacker forged with the stolen key is indistinguishable from a real one. Pass `revokeSessions: false` only when you are certain no forged token was issued. Give a reason: it is the only account of the incident the audit log will keep. This is disruptive and irreversible — for routine rotation use users_keys_rotate.

MCP tool: users_keys_revoke

Parameters

Response

Rotate this product's JWT signing key with ZERO verifier downtime. The standby key (generated now if there is none) becomes the signing key, and the old one is retired into an overlap window — BOTH key ids stay in the published JWKS until `overlapExpiresAt`, so every token signed before the rotation keeps verifying for the rest of its life and no verifier has to re-fetch anything to keep working. The overlap is the product's access-token TTL plus five minutes. After it elapses the old key is revoked automatically and stops verifying. Use users_keys_revoke instead if the key is COMPROMISED and must die now.

MCP tool: users_keys_rotate

Parameters

No parameters.

Response

What this product keeps and for how long. Returns the EFFECTIVE retention windows (spent one-time tokens, expired flow attempts, expired sessions and their refresh tokens) next to the documented defaults, the separate waitlist-entry window, the single cron that performs every sweep, and — deliberately — the list of what is NEVER swept and why. For the waitlist it also answers the two questions a published retention promise raises: whether this product's window is WIDER than the 180 days Lessly published (`waitlistWiderThanPromised`, a flag rather than a refusal), and whether the job that honours it is actually running — `lastSweep` carries the last pass this replica performed, counting THIS product's erasures only, and is NULL when it has observed none — which is not the same as a pass that erased zero. The windows are GRACE PERIODS ON TOP OF EXPIRY, never lifetimes: every live read carries its own expiry predicate, so an unswept expired row is inert and a window of 0 shortens nothing. Change them with users_config_upsert `retention`.

MCP tool: users_ops_retention_get

Parameters

No parameters.

Response

This product's service-level objectives and how it is doing against them RIGHT NOW: sign-in success rate, refresh error rate and mail-send failure rate, each with the objective, the evaluation window, the sample floor below which it is not judged, and the `users/alert.raised` kind a breach fires. Also returns the raw current window (sign-ins, refreshes, detected token reuse, mail sends) and the product's own trailing sign-in failure baseline — the number the per-product anomaly signal compares a spike against. A `status` of `insufficient_data` is NOT health: it means the window is too quiet to judge. The numbers come from ONE replica's in-process window, so treat them as a spot check rather than a fleet-wide error budget.

MCP tool: users_ops_slo_get

Parameters

No parameters.

Response

List the end-user sessions of one user of this product, newest first — one row per device, with its status, device metadata and both expiries (the sliding inactivity window and the hard time-box). Revoked and expired sessions are included so an operator can see what happened, not only what is live.

MCP tool: users_sessions_list

Parameters

Response

Read one end-user session in full: its status, device metadata, both expiries, the assurance level and factors it was established with, why it was revoked if it was, and the operator behind it if it is an impersonated session.

MCP tool: users_sessions_get

Parameters

Response

Start an impersonated session as one user of this product — support access, hard-capped. Returns an access token that expires within 30 minutes and CANNOT be refreshed; there is no refresh token. While it is in use, every credential, factor, identifier and session mutation is refused, the user is emailed (unless the product turned that notice off), and the whole thing is recorded in the audit trail against you. Give a real reason: it goes into the audit row and into that email.

MCP tool: users_sessions_impersonate

Parameters

Response

Revoke end-user sessions: pass `sessionId` to sign out one device, or `userId` to sign out every device of that user. Revocation is immediate in this toolkit's own checked verification; an access token already issued keeps verifying locally until it expires (≤10 minutes by default). Returns how many sessions this call actually revoked — a second call on the same target returns 0.

MCP tool: users_sessions_revoke

Parameters

Response

One snapshot of this product's auth deployment: directory users split by DERIVED status (active, waitlisted, banned, soft-deleted, GDPR-erased), sessions that are live right now, verified second factors, the sign-in success rate over `window`, and an abuse block — lockouts (with the MFA subset), failed sign-ins, detected refresh-token reuse and breached-password sightings. The populations are point-in-time; only the sign-in and abuse numbers honour `window`. A rising abuse block against a falling success rate is what credential stuffing looks like from here. `successRate` is null, not 0, when nothing was attempted.

MCP tool: users_stats_get

Parameters

Response

List the end users of this product, newest first. Filter by an identifier/name substring and by status. Soft-deleted users are hidden unless `includeDeleted` is true. Paginate with the opaque `nextCursor`.

MCP tool: users_users_list

Parameters

Response

Create an end user of this product with at least one identifier (email). Optionally store a password HASH — this toolkit never accepts a plaintext password, and nothing verifies the credential until auth flows land in Phase 2. Only one VERIFIED copy of an email may exist per product; unverified duplicates are allowed.

MCP tool: users_users_create

Parameters

Response

Soft-delete an end user: the record is retained with `deletedAt` set and disappears from the default list. This is NOT GDPR erasure — no data is purged, and the user can still be fetched by id.

MCP tool: users_users_delete

Parameters

Response

Fetch one end user of this product by id, including their identifiers and metadata bags. Soft-deleted users are still returned (with `deletedAt` set).

MCP tool: users_users_get

Parameters

Response

Update an end user's profile, status flags and metadata bags. Only the fields you pass change. A metadata field REPLACES that whole bag — send the full object you want stored. Write matrix in this phase: the management plane writes all three bags (public: end-user readable and may flow into the JWT; private: management plane only; unsafe: end-user writable later and never authoritative for authorization).

MCP tool: users_users_update

Parameters

Response

Ban an end user by stamping `bannedAt`. NOTE: sessions do not exist yet — until Phase 2 lands auth flows, this is a flag on the record and nothing is revoked or refused by it. Idempotent: banning an already-banned user refreshes the stamp.

MCP tool: users_users_ban

Parameters

Response

GDPR hard erasure (Art. 17) of one end user. IRREVERSIBLE and quite different from users_users_delete: the identifier and identity rows are DELETED, the profile fields nulled and all three metadata bags emptied. What survives is a tombstone — the user row with its id and `erasedAt` — so that every foreign reference and webhook consumer holding that id still resolves. The audit trail is KEPT but pseudonymized (the metadata of rows targeting this user is cleared), because a security log that erasure can rewrite is not a security log. The email is freed: registering it again creates a NEW user id. Emits `users/user.erased` so consumers purge their own copies. Idempotent — erasing an already-erased user returns the same tombstone and changes nothing.

MCP tool: users_users_erase

Parameters

Response

List the MFA factors an end user has enrolled: `totp` (an authenticator app) and `backup_codes` (single-use recovery codes), each with its status (`unverified` until enrollment was confirmed — an unverified factor gates NOTHING), when it was created and confirmed, and when it was last used. Backup codes also report `remaining`, the number still unspent; a user at 0 can no longer use that factor and should regenerate. NO SECRET IS EVER RETURNED — not the TOTP secret, not a backup code, not a digest of one. A user with no factors returns an empty list, which also means their sign-in completes at `aal1`.

MCP tool: users_factors_list

Parameters

Response

OPERATOR RESET of an end user's MFA, for the case the normal recovery cannot serve: the user lost their authenticator AND their backup codes. This does NOT remove anything now. It SCHEDULES the removal behind this product's mandatory delay (config `mfa.resetDelayHours`, default 72) and immediately emails the user's primary address an abort link; if that mailbox is alive and its owner clicks, nothing happens. When the delay elapses, EVERY factor is deleted, every backup code with it, and EVERY SESSION of that user is revoked (a session that reached `aal2` must not outlive the factor that earned it) — after which the user signs in with their first factor alone and enrolls again. Every step is audited (`factor.reset_scheduled` / `_cancelled` / `_applied`) with the `reason` you pass, so do the identity proofing FIRST and write down what it was: this tool is a supervised account takeover, and the trail is what makes it reviewable.

MCP tool: users_factors_reset

Parameters

Response

OPERATOR OVERRIDE of a user's primary email address, for the case the normal flow cannot serve: the old address is unreachable (dead mailbox, imported user), so the user cannot approve the change themselves. This does NOT swap the address now. It SCHEDULES the swap behind this product's mandatory delay (config `emailChange.overrideDelayHours`, default 72) and immediately emails the OLD address an abort link; if that mailbox is alive and its owner clicks, nothing happens. When the delay elapses the address is swapped, verified, and EVERY SESSION of that user is revoked. Every step is audited (`email_change.override_scheduled` / `_cancelled` / `_applied`) with the `reason` you pass, so do the identity proofing first and write down what it was. Use users_users_update for profile fields; this tool is only for the identity a user signs in with.

MCP tool: users_users_set_primary_identifier

Parameters

Response

Lift a ban by clearing `bannedAt`. See users_users_ban: the flag has no enforcement until Phase 2. Idempotent.

MCP tool: users_users_unban

Parameters

Response

Export the end users of this product as pages of full records (profile, identifiers, metadata bags), using the same filters as users_users_list. Password hashes are NEVER included — neither a PHC hash nor an imported foreign one. Exporting credentials is deferred to a later phase, behind explicit elevated approval; until that gating exists, a hash cannot leave this toolkit. Every call is AUDITED (action `users.export`, with the filter and the row count), so this is not a silent read: use it for migrations, backups and subject-access requests, not as a listing shortcut. Page through with `nextCursor`.

MCP tool: users_users_export

Parameters

Response

Bulk-import end users into this product, up to 500 rows per call — batch client-side beyond that. Hashes only: pass `password.phcHash` for an argon2id PHC string, or `password.foreignHash` + `foreignHashAlgo` (bcrypt/argon2/pbkdf2/scrypt) for a hash from the system you are migrating off. A foreign hash is stored INERT — nothing verifies it until sign-in lands in Phase 2, where it is checked once and rehashed — so set `requiresReset: true` on rows whose source hash you do not trust. IDEMPOTENT by canonical identifier: a row whose email already exists VERIFIED in this product is skipped, not duplicated, so re-running the same file is safe. Imported identifiers default to verified (unlike users_users_create) — pass `verified: false` per identifier for addresses the source system never confirmed. Returns a PER-ROW report ({row, status, userId, reason}) plus counts: one malformed row never fails the batch. Emits ONE batch event (`users/user.imported`, with counts) rather than a per-user created event, and writes ONE audit row.

MCP tool: users_users_import

Parameters

Response

Invite somebody to this product by email. Creates the user immediately with an UNVERIFIED identifier and NO credential — they appear in users_users_list straight away but cannot sign in until they accept — then mails a one-time invite link. Accepting the link sets their first password and verifies the address; no session comes from the link itself. IDEMPOTENT by address: re-inviting returns the SAME user (`created: false`), and whether it re-mails is a cooldown decision, so pressing the button twice cannot flood a mailbox (`mailed: false` means the invite is live but no email went out this time). Refuses an address that already belongs to a signed-up user. Requires a verified sender in this product's mail toolkit (config `email.from`); without one nothing is sent and `mailed` is false.

MCP tool: users_users_invite

Parameters

Response

GDPR-erase one waitlist signup: the entry with its attribution and consent proof is deleted and the directory row is hard-erased (the id survives as a tombstone, the PII does not). IRREVERSIBLE. Use it for a right-to-erasure request; routine cleanup of stale pending entries happens on its own through the retention sweep.

MCP tool: users_waitlist_erase

Parameters

Response

Count this product's waitlist by funnel stage. `pending` is people waiting, `unconfirmed` is double-opt-in signups whose address never confirmed (they are NEVER invited), `invited` have a live invite, `registered` accepted it and are now full users, `withdrawn` asked to be removed. One consistent snapshot, not five separate reads.

MCP tool: users_waitlist_funnel

Parameters

No parameters.

Response

Import a LEGACY waitlist into this product. Each row becomes a directory user in state `waitlisted` (no credential — a waitlist signup has nothing to sign in with) plus a WaitlistEntry whose consent proof is stored VERBATIM: the policy version, the timestamp and the source the OLD system recorded, never the import time. Rides the Phase 1 bulk import, so it is IDEMPOTENT by canonical identifier — re-running the same file skips instead of duplicating — and reports PER ROW ({row, status, userId, reason}) so one bad row never fails the batch. Addresses that already have an entry are skipped `already_on_list`; addresses on the suppression list (they withdrew) are skipped `suppressed` and are NOT resurrected. SENDS NO EMAIL: an import is a migration, not a signup gesture. Imported addresses land UNVERIFIED, and by default confirmed — pass `confirmed: false` for rows the source system never reached, which then count as `unconfirmed` and are never invited. Up to 500 rows per call.

MCP tool: users_waitlist_import

Parameters

Response

Promote waitlisted users by sending them the STANDARD invite email — the same one-time invite link `users_users_invite` sends, so accepting it sets their first password, verifies their address and turns the entry into `registered`. Batched: pass up to 100 user ids. Entries that already registered, that belong to another product, or whose address is on the suppression list (they withdrew) are SKIPPED with a reason rather than mailed. Requires a verified sender in this product's mail toolkit (config `email.from`).

MCP tool: users_waitlist_invite

Parameters

Response

List this product's waitlist entries, newest first. Each row is a directory user in state `waitlisted` PLUS the feature-local funnel state: where the signup came from (referrer/UTM), the consent proof recorded for it, and its status. Filter by `status` to work one stage of the funnel, or by `confirmed: false` to find double-opt-in signups whose address never confirmed. Paginate with `cursor`.

MCP tool: users_waitlist_list

Parameters

Response

List this product's webhook endpoints, newest first — url, subscribed events, paused state and the visible prefix of the current signing secret. The secret itself is never here.

MCP tool: users_webhooks_list

Parameters

No parameters.

Response

Register an outbound webhook endpoint for this product. Deliveries are signed with the Standard Webhooks wire format (webhook-id / webhook-timestamp / webhook-signature). The signing secret is returned EXACTLY ONCE — it is derived, never stored, so a lost secret is rotated with users_webhooks_rotate_secret, never recovered.

MCP tool: users_webhooks_create

Parameters

Response

Delete a webhook endpoint, its signing secrets and its delivery log. Immediate and final; deliveries already in flight stop.

MCP tool: users_webhooks_delete

Parameters

Response

One webhook endpoint. Another product’s endpoint and one that never existed answer identically.

MCP tool: users_webhooks_get

Parameters

Response

Change a webhook endpoint: its url, its subscribed events, its description, or `active` to pause and resume delivery without losing the endpoint or its secret.

MCP tool: users_webhooks_update

Parameters

Response

This endpoint's recent deliveries, newest first: event type and id, status (pending / succeeded / failed), attempt count, the last response status and the last error. This is where 'my webhook never arrived' is answered.

MCP tool: users_webhooks_deliveries_list

Parameters

Response

Mint a NEW signing secret for this endpoint and return it exactly once. The previous secret keeps verifying for 24 hours — both signatures ride the webhook-signature header — so a receiver can swap its copy without dropping a delivery.

MCP tool: users_webhooks_rotate_secret

Parameters

Response