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

Returns object.

Issue an API key for this product. type='publishable' mints a non-secret browser key (upk_…) that only names this product and stays readable afterwards. It is the only type: the secret server key (usk_…) is retired — the one route it authorized is now checked by the public edge against the product's platform public key.

MCP tool: users_apikeys_create

Parameters

Response

Returns object.

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

Returns object.

Read ONE of this product's API keys by id — its label, type, visible prefix, when it was issued and whether it has been revoked. The same shape users_apikeys_list returns per row. A server key's SECRET is not here and never will be: that value existed in exactly one response, ever, and what is stored is a hash. An unknown id, a malformed id and a key belonging to another product all answer alike.

MCP tool: users_apikeys_get

Parameters

Response

Returns object.

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

Returns object.

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

Returns object.

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). `email.templates` sends an auth email from a PUBLISHED template in this product's mail toolkit instead of the built-in one ({ "<purpose>": "<template id>" }, null unbinds). The template is not checked by this server: if mail cannot render it at send time, the built-in email is sent instead and the fallback is audited. Variables Users passes, per purpose (`*` = required: the template must use it; `?` = sent only sometimes, so the template must not require it; the rest are always sent): sign_in: code*, expires_in_minutes, link_url? verify: code*, expires_in_minutes, link_url? password_reset: link_url*, expires_in_minutes invite: link_url*, expires_in_minutes email_change_confirm: link_url*, expires_in_minutes email_change_approve: link_url*, expires_in_minutes, new_address email_change_revert: link_url*, expires_in_minutes, new_address email_change_override_cancel: link_url*, expires_in_minutes, new_address, takes_effect_in password_changed: none new_device: browser? email_change_completed: none email_change_reverted: none mfa_reset_scheduled: link_url*, expires_in_minutes, takes_effect_in mfa_reset: none impersonation: reason waitlist_confirm: link_url*, expires_in_minutes waitlist_joined: link_url*, expires_in_minutes

MCP tool: users_config_upsert

Parameters

Response

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

One snapshot of this product's auth deployment: directory users split by DERIVED status (active, contacts, 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

Returns object.

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. CONTACTS — people the Product knows who have no credential and have never signed in — are hidden by default, exactly as waitlist signups and test users are; pass `kind: "contact"` to list only them, or `includeContacts: true` to see both. Filter further by `stage` (new, contacted, replied, engaged, converted, lost) and by a single `tag`, both ANDed with everything else. `query` matches a substring of the display name or of ANY identifier's canonical value — an address, a phone in E.164, a handle. Paginate with the opaque `nextCursor`.

MCP tool: users_users_list

Parameters

Response

Returns object.

Create an end user of this product with at least one email identifier. Supply password to store a password hash; omit it to create the user without a password identity. Supply only hashes in password fields; do not send plaintext passwords. Only one verified copy of an email is allowed per product; unverified duplicates are allowed. Pass `kind: "contact"` to record somebody the Product knows who cannot sign in: a contact may not carry `password`, `waitlisted` or `requiresReset` (refused with `contact_cannot_hold_credentials`), is hidden from the default users_users_list view, and is never counted as a retained user. `stage` and `tags` set the relationship state; tags are stored trimmed, lowercased and de-duplicated. Besides `email`, an identifier may be a CONTACT CHANNEL — `phone`, `telegram`, `linkedin` or `x`. A channel is how to REACH somebody, not how they sign in: it is always stored `unverified` (a `verified: true` on one is ignored), it can never start a sign-in, carry a one-time code or be verified, and it is canonicalised by its own rule — `phone` to E.164 (`+7 (999) 123-45-67` is stored `+79991234567`), `telegram` and `x` lowercased without a leading `@`, `linkedin` to the public-profile slug, so a full `linkedin.com/in/<slug>` URL and the bare slug are one value. A value that does not fit its type is refused with `invalid_identifier`. One record may not carry the same channel twice (`duplicate_identifier`), but two different people MAY share one — a company phone is not a conflict. A contact may carry a channel and no address at all.

MCP tool: users_users_create

Parameters

Response

Returns object.

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

Returns object.

Fetch one end user of this product by id, including their identifiers and metadata bags. Soft-deleted users are still returned (with `deletedAt` set). Identifiers include contact channels (`phone`, `telegram`, `linkedin`, `x`) alongside emails; a channel is always `unverified`.

MCP tool: users_users_get

Parameters

Response

Returns object.

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). `stage` moves the person along the funnel and publishes `users/user.stage-changed`; a patch that changes ONLY the stage deliberately does not also publish `users/user.updated`, so a workflow that writes stages does not wake itself. `tags` REPLACES the whole list. `kind` is NOT editable here and is refused with `kind_not_updatable`: a contact becomes an account only by proving an address.

MCP tool: users_users_update

Parameters

Response

Returns object.

Ban an end user by stamping `bannedAt` and revoking their live sessions. Banned users are refused at sign-in. Banning an already-banned user refreshes the stamp.

MCP tool: users_users_ban

Parameters

Response

Returns object.

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

Returns object.

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

Returns object.

List the passkeys (WebAuthn credentials) an end user has registered: the credential's id, the name the user gave it, its transports (`internal` is a platform passkey on the device itself, `usb`/`nfc`/`ble` a security key, `hybrid` a phone used from another device), the authenticator model's `aaguid`, whether the credential is `backedUp` (synced by the platform, so it survives losing the device), its sign counter and when it was last used. NO KEY MATERIAL IS EVER RETURNED — the public key is deliberately absent: nothing on this plane needs it, and it is a stable cross-site fingerprint for the device holding it. A user with passkeys signs in without a password, and reaches `aal2` in one gesture whenever their authenticator verified them.

MCP tool: users_passkeys_list

Parameters

Response

Returns object.

REVOKE ONE passkey — the support path for a lost or stolen device. It takes effect IMMEDIATELY and permanently: that credential can never sign in again, and the user re-registers from a device they still hold. It is REFUSED (`status: 'failed'`, code `passkey_last_way_in`) when this credential is the account's only remaining way in — no other identity and no verified identifier — because removing it would strand the account forever; add another way in first. It cannot CREATE a passkey: there is no admin-side registration in this toolkit at all, since a credential an operator could enroll is one they could keep. Every revoke is audited (`passkey.deleted`) with the `reason` you pass, so do the identity proofing FIRST and write down what it was.

MCP tool: users_passkeys_revoke

Parameters

Response

Returns object.

Read ONE passkey of an end user by id — the name they gave it, its transports, the authenticator model's `aaguid`, whether it is `backedUp`, its sign counter and when it was last used. The same shape users_passkeys_list returns per row. NO KEY MATERIAL IS EVER RETURNED: the public key is deliberately absent here as it is there. A credential id that belongs to another user answers 404 exactly like one that never existed.

MCP tool: users_passkeys_get

Parameters

Response

Returns object.

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

Returns object.

List a person's logged interactions, newest first — by when they were LOGGED, so a backdated touch still appears on the first page. Filter by channel. Paginate with the opaque `nextCursor`.

MCP tool: users_touches_list

Parameters

Response

Returns object.

Log an interaction with a person — a message, a call, a meeting, a note, or an email sent OUTSIDE the platform. Email this toolkit sent is NOT logged here; read those from the mail toolkit. `occurredAt` is when it HAPPENED and may be backdated; omit it to mean now. A 'note' or a 'meeting' takes direction 'none'. Who logged it is taken from your identity and can never be set from the body.

MCP tool: users_touches_create

Parameters

Response

Returns object.

Discard a touch you logged. A touch somebody ELSE logged answers 404, exactly as a touch that does not exist does. Pass `force: true` to remove it anyway, which is recorded in the audit trail along with the original author. There is no undo.

MCP tool: users_touches_discard

Parameters

Response

Returns object.

Correct a touch you logged — its text, when it happened, or both. A touch somebody ELSE logged answers 404, exactly as a touch that does not exist does: the refusal must not tell you the row is there. Pass `force: true` to edit it anyway, which is recorded in the audit trail along with the original author.

MCP tool: users_touches_update

Parameters

Response

Returns object.

Lift a ban by clearing `bannedAt`. This removes the sign-in ban set by users_users_ban; previously revoked sessions stay revoked. Idempotent.

MCP tool: users_users_unban

Parameters

Response

Returns object.

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. Filter by `kind`, or pass `includeContacts: true`, to export accounts and contacts in one pass — contacts are excluded by default, the same rule this export already applies to waitlist signups and test users. Page through with `nextCursor`. Identifiers include contact channels (`phone`, `telegram`, `linkedin`, `x`) alongside emails; a channel is always `unverified`.

MCP tool: users_users_export

Parameters

Response

Returns object.

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, when 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. Rows may be CONTACTS (`kind: "contact"` — known to the Product, no credential, never signed in); a contact row carrying `password`, `waitlisted` or `requiresReset` comes back as a FAILED ROW with `contact_cannot_hold_credentials`, never as a rejected batch. The result and the `users/user.imported` event carry a `contacts` count of the rows actually created. Contact channels (`phone`, `telegram`, `linkedin`, `x`) import as UNVERIFIED regardless of this tool's `verified: true` default — nothing here can prove a phone or a handle, so there is no confirmation to carry over. A row whose channel value does not fit its type comes back as a FAILED ROW with `invalid_identifier`, never as a rejected batch.

MCP tool: users_users_import

Parameters

Response

Returns object.

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

Returns object.

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

Returns object.

Read ONE waitlist entry by user id — its funnel status, the address it joined with, where the signup came from (referrer/UTM), the consent proof recorded for it, and the timestamp of every stage it passed. The same shape users_waitlist_list returns per row. A user who is not on this product's waitlist answers 404.

MCP tool: users_waitlist_get

Parameters

Response

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.

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

MCP tool: users_webhooks_get

Parameters

Response

Returns object.

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

Returns object.

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

Returns object.

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

Returns object.