<!-- Generated by scripts/gen-mcp-reference.ts from the MCP tool registrations and libs/contracts Zod schemas. Do not edit by hand — run `pnpm docs:gen` to regenerate. -->

MCP tool reference

Every management tool the auth.is MCP server exposes, generated directly from the tool registrations and their libs/contracts Zod input schemas — so this page can never drift from what the server actually advertises. Each tool lists its exact parameters, types, and constraints. The description under each name is the verbatim text the model sees in tools/list.

Onboarding

Confirm the connection and get a tailored, ordered setup checklist.

whoami

Return the authenticated auth.is user (id, email, name) and the teams they belong to. Use this first to confirm the connection is healthy and to decide what to do next: no teams yet means the user should create one. For a guided, tailored next-step checklist, call get_started instead. See https://docs.auth.is/quickstart.

This tool takes no parameters.

get_started

Inspect the caller’s account and return a tailored, ORDERED setup checklist, each step naming the exact tool to call next: no team → create_team; a team but no clients → create_client; clients but no federation providers → add_identity_provider; no custom theme → preview_theme; everything set → the maintenance tools (rotate_signing_keys, rotate_client_secret) and docs. Call this whenever the user asks "what now?" or at the start of a session. Fast and resilient: it makes only a few reads and still returns what it learned if one of them fails. See https://docs.auth.is/quickstart.

This tool takes no parameters.

Teams

The top-level tenant; a team owns exactly one issuer.

list_teams

List every team the authenticated user belongs to, with their role (owner or member) in each. Use this to find a teamId before calling get_team, list_members, or invite_member. An empty list means the user has no team yet — offer create_team. See https://docs.auth.is/teams.

This tool takes no parameters.

get_team

Return a single team and its issuer (id, slug, configVersion). Requires a teamId from list_teams or create_team. The returned issuer.id is what the client, provider, issuer-settings, and signing-key tools all take as their issuerId. You must be a member of the team; if you are not, this returns a not-found error (auth.is never reveals whether a team you cannot access exists). See https://docs.auth.is/teams.

create_team

Create a new team and, atomically, its first issuer — a live OIDC provider served at {slug}.auth.is. The caller becomes the team owner. This takes effect immediately: the issuer serves OIDC discovery the instant this returns, and the result includes the discovery URL so you can verify it. The slug must be a free, non-reserved DNS label (lowercase letters, digits, hyphens; 3–63 chars); a taken or reserved slug comes back as a conflict — pick another. This is the first thing a new user does; everything else needs the teamId and issuer.id it returns. See https://docs.auth.is/teams.

Issuers

The per-team OIDC provider and its settings.

get_issuer

Return an issuer’s configuration: slug, configVersion, and settings (registration mode, session TTL, passkey default, resource servers, theme). Never returns signing-key material. Requires an issuerId — take it from get_team or create_team (team.issuer.id). Members of the owning team only; others get a not-found error. See https://docs.auth.is/issuers.

update_issuer_settings

Merge a partial settings patch onto an issuer — any of registrationMode ("open" or "invite_only"), sessionTtlSeconds (300–2592000), or passkeysDefaultEnabled — leaving the other settings untouched. Provide at least one field. This takes effect immediately: it bumps configVersion and invalidates the running IDP’s cache, so the change is live on the login pages at once. Owner only; a non-owner member gets a permission error. Requires an issuerId from get_team/create_team. See https://docs.auth.is/issuers.

Clients

The OAuth/OIDC client registrations applications use to log users in.

list_clients

List every OAuth/OIDC client under an issuer as secret-free summaries (client_id, name, confidential flag, grant types, auth method). Use it to find a client_id before get_client or any client mutation. Requires an issuerId from get_team/create_team. Members only; others get a not-found error. See https://docs.auth.is/clients.

get_client

Return one client’s full non-secret metadata: redirect URIs, grant and response types, auth method, PKCE requirement, passkeys flag, self-signup flag (registration_enabled), enabled federation providers, token TTLs, and any theme override. The secret is NEVER included, not even masked. Requires an issuerId (from get_team/create_team) and a client_id (from list_clients). Members only. See https://docs.auth.is/clients.

create_client

Register a new OAuth/OIDC client (application) under an issuer. A confidential client — token_endpoint_auth_method other than "none" — is issued a secret that is returned in this response ONE TIME and never again; a public/PKCE client (method "none") gets no secret. Set grant_types (e.g. ["authorization_code","refresh_token"]) and, for the authorization-code flow, redirect_uris (https only in production; http://localhost is allowed in dev). Set registration_enabled=true to offer end-user self-signup ("Create account") on this client’s login page — off by default; it also requires the issuer’s registrationMode to not be "invite_only" (see update_issuer_settings). This takes effect immediately — the client can begin OAuth flows against the issuer at once. If a secret is returned, hand it to the user right away to store securely. Owner only. Requires an issuerId from get_team/create_team. See https://docs.auth.is/clients.

update_client

Update a client’s general fields: name, post_logout_redirect_uris, require_pkce, and registration_enabled (offer end-user self-signup on the client’s login page; also requires the issuer’s registrationMode to not be "invite_only"). Provide at least one. For redirect URIs, providers, passkeys, token TTLs, or the secret, use the dedicated tool instead. Takes effect immediately (bumps configVersion, invalidates the IDP cache). Owner only. Requires an issuerId (from get_team/create_team) and a clientId (from list_clients). See https://docs.auth.is/clients.

update_client_redirect_uris

REPLACE a client’s entire redirect_uris set with the list you pass (this is not additive — any URI you omit is removed). https only in production; http://localhost is allowed in dev. Takes effect immediately on the running issuer, so a redirect URI dropped here stops being accepted at once and one added here starts working at once. Owner only. Requires an issuerId (from get_team/create_team) and a clientId (from list_clients). See https://docs.auth.is/clients.

rotate_client_secret

Generate a NEW confidential secret for a client and return it ONE TIME in this response — it can never be retrieved again. The previous secret STOPS WORKING IMMEDIATELY, so any integration using the old secret will break until updated. Only valid for confidential clients. Hand the new secret to the user right away to store securely. Owner only. Requires an issuerId (from get_team/create_team) and a clientId (from list_clients). See https://docs.auth.is/clients.

toggle_client_passkeys

Enable or disable the passkey second-factor and enrollment offer for a client (passkeys_enabled true/false). Takes effect immediately on the client’s login screens. Owner only. Requires an issuerId (from get_team/create_team) and a clientId (from list_clients). See https://docs.auth.is/clients.

set_client_providers

RESTRICT which of the issuer’s federation providers this client offers on its login screen, by passing the exact set of provider keys (enabled_providers) — the login page shows the intersection of these and the issuer’s enabled providers. This replaces the client’s set. Every key must be a configured provider (see list_providers); an unknown key is rejected. Takes effect immediately. Owner only. Requires an issuerId (from get_team/create_team) and a clientId (from list_clients). See https://docs.auth.is/identity-providers.

update_client_token_ttls

Set a client’s id_token and/or refresh_token lifetime in seconds (provide at least one). Bounds mirror the IDP exactly: id_token 60–14400s, refresh_token 60–4838400s; a value outside the range is rejected rather than silently clamped. Takes effect immediately on newly issued tokens. Owner only. Requires an issuerId (from get_team/create_team) and a clientId (from list_clients). See https://docs.auth.is/clients.

delete_client

WARNING: permanently deletes a client and cannot be undone. It revokes the client’s grants (killing its refresh tokens) and hard-deletes it, bumping configVersion so the issuer rejects the client immediately — any application using this client_id will stop being able to authenticate at once. Confirm with the user before calling. Owner only. Requires an issuerId (from get_team/create_team) and a clientId (from list_clients). See https://docs.auth.is/clients.

Members

A team's roster and its owner-only role/removal mutations.

list_members

List every member of a team with their role (owner/member) and join date. Use it to find a userId before update_member_role or remove_member. Requires a teamId from list_teams. Members of the team only; others get a not-found error. See https://docs.auth.is/members.

update_member_role

Promote a member to owner or demote an owner to member (role "owner" or "member"). Owner only. Demoting the team’s LAST owner is refused with a conflict — a team must always keep at least one owner, so transfer ownership first. Requires a teamId (from list_teams) and the target userId (from list_members). See https://docs.auth.is/members.

remove_member

WARNING: removes a member from a team, revoking their access to it. Owner only, EXCEPT a member may remove themselves (leave). Removing the team’s LAST owner is refused with a conflict — transfer ownership first. Confirm with the user before calling. Requires a teamId (from list_teams) and the target userId (from list_members). See https://docs.auth.is/members.

Invites

Pending invitations that let a new member join a team.

list_invites

List a team’s invitations — pending ones plus recently accepted, revoked, or expired — each with a derived status. No token material is ever returned. Use it to find an inviteId to revoke, or to check whether an invite is still pending. Owner only. Requires a teamId from list_teams. See https://docs.auth.is/invites.

invite_member

Create a single-use, time-limited invitation and EMAIL a join link to the address, with role "member" (default) or "owner". The raw link is sent only to the invitee’s inbox and is never returned here — this responds with a masked invite view. Refused with a conflict if the email already belongs to a member or a live pending invite (revoke that one to re-send). Owner only. Requires a teamId from list_teams. See https://docs.auth.is/invites.

revoke_invite

Revoke a still-pending invitation so its join link can no longer be redeemed. Only pending invites can be revoked (an already accepted, expired, or revoked one returns a not-found error). Owner only. Requires a teamId (from list_teams) and an inviteId (from list_invites). See https://docs.auth.is/invites.

Identity providers

The upstream IdPs an issuer offers as "Continue with …" buttons.

list_providers

List an issuer’s configured federation providers with a MASKED config (clientId and non-secret fields visible; the upstream secret collapses to hasSecret — the value is never returned). Use it to find a provider key before update/remove, or to see what set_client_providers can reference. Requires an issuerId from get_team/create_team. Members only. See https://docs.auth.is/identity-providers.

add_identity_provider

Configure an upstream identity provider the issuer offers as a "Continue with …" button. Common fields: issuerId (from get_team/create_team), a URL-safe key (2–63 chars, unique per issuer — used in the callback path), a display name, clientId, optional clientSecret (write-only), and optional scopes. Type-specific config, validated per type: type "google" takes optional hostedDomains[]; type "entra" REQUIRES tenantId (an Azure tenant GUID or common/organizations/consumers); type "kenni" and type "oidc" REQUIRE issuerUrl (an http(s) issuer URL, https in production). Sending a field that does not belong to the type is rejected. This takes effect immediately — the login button appears on the running issuer at once. A key already in use is a conflict. Owner only. See https://docs.auth.is/identity-providers.

update_identity_provider

Partially update a federation provider (provide at least one field). The type is IMMUTABLE — to change it, remove and re-add. Mutable: name, enabled, clientId, scopes, and the type-appropriate config field (hostedDomains for google, tenantId for entra, issuerUrl for kenni/oidc); a field wrong for the provider’s type is rejected. Secret handling is tri-state: OMIT clientSecret to keep the current one, send null to remove it (make the upstream public), or send a string to replace it. Setting enabled=false hides the button on the running login page immediately. Owner only. Requires an issuerId (from get_team/create_team) and the providerKey (from list_providers). See https://docs.auth.is/identity-providers.

remove_identity_provider

WARNING: removes a federation provider from an issuer; its login button disappears immediately. This is BLOCKED with a conflict (and a count) while any user still signs in through it, because removing it would cascade-delete those users’ login methods — delete or migrate those linked identities first. Confirm with the user before calling. Owner only. Requires an issuerId (from get_team/create_team) and the providerKey (from list_providers). See https://docs.auth.is/identity-providers.

Theming

Read, preview, tweak, and apply the generated brand theme.

get_theme

Return the brand theme currently applied to an issuer’s login pages, and — when a clientId is given — that client’s theme override plus the effective theme (client override wins over the issuer theme). A null theme simply means the default palette is in use. Requires an issuerId from get_team/create_team; clientId (from list_clients) is optional. To CHANGE a theme, use the theme tools. See https://docs.auth.is/theming.

preview_theme

Generate a brand theme for an issuer from an accent colour and return a live, signed PREVIEW URL the user can open to see their actual login page rendered with it — plus both light and dark palettes and a WCAG contrast (AA) report. READ-ONLY: nothing is stored and the live login pages are unchanged; follow with apply_theme once the user likes it. Input: an issuerId (from get_team/create_team), a theme (accent hex required; optional grayTint, radius, logo URLs, and per-mode token overrides), and an optional appearance ("light"/"dark"/"inherit") to force the preview document’s mode. The preview URL expires after a few minutes, so share it promptly. If the contrast report flags an AA failure, relay it to the user before applying. Members of the owning team only. See https://docs.auth.is/theming.

tweak_theme_stop

Override a SINGLE generated colour stop (or the login gradient) on the issuer’s current theme, then return a fresh live preview — for the rare case the auto-generated palette needs one hand-tuned token. It reads the issuer’s current theme, layers your one override on top, and previews it; it does NOT save (follow with apply_theme to persist). The issuer must already have a base theme (set one with preview_theme + apply_theme first). token must be a generated theme variable — one of --background, --foreground, --card, --card-foreground, --primary, --primary-foreground, --muted, --muted-foreground, --accent, --accent-foreground, --destructive, --destructive-foreground, --border, --input, --ring, or --authis-login-gradient; value is a literal CSS colour (e.g. an "oklch(...)" or "#RRGGBB") or, for the gradient token, a CSS background-image. mode picks which appearance the override applies to. An override bypasses the contrast guarantees, so check the returned report. Requires an issuerId from get_team/create_team. Members only. See https://docs.auth.is/theming.

apply_theme

Persist a theme as the issuer’s brand — the WRITE that preview_theme sets up. Preview first (preview_theme) and confirm the look before calling. It takes effect immediately: it bumps configVersion and invalidates the running IDP cache, so every login page under the issuer re-themes with no restart. Pass theme=null to clear back to the workspace default. The response echoes the WCAG contrast (AA) report — relay any failure to the user. Owner only; a non-owner gets a permission error. Requires an issuerId from get_team/create_team. See https://docs.auth.is/theming.

apply_client_theme

Persist a PER-CLIENT theme override for one client under an issuer. Resolution is client-over-issuer: on that client’s login screens this theme wins over the issuer’s theme; other clients keep the issuer theme. Preview first with preview_theme (which previews the issuer host; a client override renders the same generator output). Takes effect immediately (configVersion bump + IDP cache invalidation). Owner only. Requires an issuerId (from get_team/create_team) and a clientId (from list_clients). See https://docs.auth.is/theming.

Signing keys

The issuer JWKS lifecycle and zero-downtime rotation.

list_signing_keys

List an issuer’s RS256 signing keys as PUBLIC lifecycle metadata only — each key’s kid, status (active, next, or retired), and timestamps — ordered active → next → retired. Never returns key material (the issuer’s jwks_uri is the public key surface). Use this to confirm the state of a rotation. Requires an issuerId from get_team/create_team. See https://docs.auth.is/signing-keys.

rotate_signing_keys

Drive ONE step of the zero-downtime signing-key rotation runbook on an issuer. step="prepare" mints a published-but-not-yet-signing "next" key; step="promote" makes "next" the active signer and retires the old active key (still published so already-issued tokens keep verifying); step="retire" drops retired keys past the safety window (or every retired key with force=true — the key-compromise path). Each successful step takes effect immediately: it bumps configVersion and invalidates the IDP cache. Never returns key material. Owner only. The normal cadence is prepare, wait for propagation, then promote — confirm with the user before promote or a forced retire. Requires an issuerId from get_team/create_team. See https://docs.auth.is/signing-keys.

Next steps