Return the authenticated principal's profile (account details + email verification status). Works for both human and service principals.

Patch the authenticated user's profile. Omitted fields are left untouched. model_config and capabilities apply to service accounts only.

username is the unique, public handle (3-64 chars, only letters/digits and ._@+-). Case-insensitive uniqueness is enforced at the database level — a collision returns 4002 validation_failed rather than overwriting another row. The same field can also be edited by other services via the account.profile.update_requested RabbitMQ event (see Events).

Two modes selected automatically by the BE based on whether the account currently has a password_hash:

• Change mode (has_password = true): the request must

supply the correct current_password. We verify it against the stored hash, accept the swap, then revoke every active session except the one making this request (so the tab the user is sitting in doesn't get logged out).

• First-time set mode (has_password = false): typical

for users who signed up via Google or Firebase and never set a password. The current_password field is ignored in this mode — there is nothing to verify — but the caller must still be authenticated via JWT. After success the account has has_password = true and future calls hit the change-mode path.

The mode is decided server-side from the database; the FE uses the has_password field from /me to pick between a "Change password" and a "Set password" form.

Service accounts cannot call this — they have no password. Rate limit: 5 / minute / IP.

Step 1 of the verify-new-email flow. Does NOT change the email immediately — instead sends a confirmation link to the new address and a security notice to the old one. The old email stays active until the new one is confirmed (step 2). Guards against typos and session-hijack.

Re-auth: accounts that have a password MUST send current_password. SSO-only accounts (NULL password) skip it — the valid session is the only credential they have.

Errors:

• 422 — new_email invalid, or current_password missing

on a password account.

• 401 — current_password incorrect.
• 409 — new_email already belongs to another account.

Sessions are not revoked by an email change (it's not a credential change). The confirmation link expires in 1 hour.

Step 2 — public (the token from the confirmation email is the auth). Consumes the token, swaps the account's email, marks it verified, and publishes account.account.updated / account.account.email_changed to exchange account.events. Single-use: the token is dropped after a successful swap.

Two entry points hit the same logic:

• This JSON endpoint (POST) — for a FE-driven confirm page.
• GET /confirm-email-change?token=… — the link in the

confirmation email lands here directly; the backend runs the same swap and renders a branded HTML result page (mirrors GET /verify-email). No FE page required.

For platform=wacca-mobile requests the email's primary button is a wacca:// deeplink with the https link as fallback — but that's set at registration/login time, not here.

Errors:

• 422 — token missing / invalid / expired.
• 409 — the new email was taken by someone else during the

confirmation window.

List every active session for the authenticated user. The session backing the current request is flagged with is_current: true. Also available at /api/v1/sessions (legacy path).

Revoke a specific session by id. The user can revoke any of their own sessions, including the current one (which terminates the calling session). Also available at /api/v1/sessions/{session_id}.

Snapshot of which external identity providers are currently linked to the authenticated account. Today the only one is Google; the response shape is forward-compatible — new providers added later become additional entries in the providers array without changing the wrapper.

For Google, linked_email carries the email of the linked Google identity (e.g. arian.personal@gmail.com) which may differ from the account's own email (arian@ikavia.com). The FE renders "Connected as {linked_email}" so the user knows which Google account is attached. Absent from the response when the provider is not linked.

can_disconnect_google is true only when the user has a password set; this lets the UI disable the disconnect button for Google-only accounts so they don't lock themselves out.

Link a verified Google identity to the currently-signed-in account. The body shape is identical to /auth/google: the credential is the raw JWT returned by Google Identity Services (web) or the native Google SDK (Android / iOS).

Validation:

• Google ID token signature, iss, aud, exp must all

check out (same JWKS-verified path as /auth/google).

• Google email_verified must NOT be false.
• The token's email is NOT required to match the

account's email. A typical use case is a work account (arian@ikavia.com) linked to a personal Google identity (arian.personal@gmail.com); both are persisted so the FE can display the Google address alongside the account address.

Identity model: google_sub (Google's stable, never- reused subject id) is the lookup key — DB UNIQUE constraint sits there. google_email is persisted only for display; on every successful login the BE refreshes it from the token so a user who later changes their Google primary email still sees the right value.

Idempotent: if the same Google sub is already linked to this account, the call refreshes the stored google_email and returns 200 with the current status. Linking a DIFFERENT sub to a row that already has one returns 4005 duplicate_entry — the user must disconnect the old Google identity first. Linking a sub already owned by ANOTHER account also returns 4005.

Clear the account's google_sub AND google_email. After this call the user can no longer sign in via Google for this account — they must use password (or re-link Google later).

Lock-out guard: if the account has no password set (proxied today by password_hash IS NULL), the call returns 4002 with a message instructing the user to set a password first via /auth/password-reset. Idempotent: calling DELETE when Google is not linked returns 200 with the current status.

Audit-log entries where the authenticated user is the actor. Paged. The actor_id filter is forced server-side to the calling user, so callers cannot pivot to another user's feed.

Action vocabulary (dot-notation, used in action filter and action field of returned items):

• account.profile_updated, account.accessed
• auth.login, auth.login_failed, auth.logout,

auth.token_refreshed, auth.password_changed, auth.password_reset

• member.invited, member.removed
• invitation.cancelled
• service_account.archived, service_account.paused,

service_account.resumed

• api_key.created, api_key.revoked

New actions may be added without a docs revision; consumers should tolerate unknown values (display as-is, don't reject).

Authenticated user directory search. Match is ILIKE %q% against either display_name OR email. Returns the minimum fields a "find someone" picker needs.

Mitigations against enumeration (this endpoint is global, which is intentional but exposed):

• Server enforces APP__SECURITY__SEARCH__MIN_QUERY_LENGTH

(default 3 characters). Shorter q → 422.

• per_page is clamped server-side to

APP__SECURITY__SEARCH__MAX_PER_PAGE (default 50).

• Dedicated rate-limit bucket (search, default **30/min/IP

fail-closed**) — tighter than general, fail-closed so a limiter outage doesn't open a scraping window.

Excluded from results: soft-deleted accounts (deleted_at IS NOT NULL) and deactivated accounts — the user closed their account; surfacing them in pickers would re-attach them to other people's workflows.

Service principals should use the existing s2s endpoints GET /accounts/{id} / POST /accounts/bulk-lookup instead — fuzzy search isn't part of the s2s contract.

Errors:

• 422 / 4002 — q shorter than the configured minimum.
• 429 / 4008 — rate-limit hit, includes retry_after.

Returns the public profile of the account with the given UUID. 404 when the account doesn't exist or has been soft-deleted; 403 when the caller is a human principal (use /api/v1/me instead); 422 when {id} isn't a UUID.

Batch variant. Send up to 100 UUIDs in one request and get back the matching profiles in a single DB round-trip. Use this when enriching a list response — looping the single-id endpoint would N+1 the DB.

Behaviour:

• Empty ids array → 200 with items: [] (no DB hit).
• Duplicates in ids are de-duplicated; each account

appears at most once in items.

• IDs with no matching account are silently omitted —

the consumer can diff against their request to detect gaps.

• Output order is not guaranteed to match input

order. Build a Map<id, profile> on the consumer side and look up by id.

Errors:

• 403 — caller is a human principal.
• 422 — ids has more than 100 entries, or any entry

is not a UUID. The whole request is rejected; we do not return partial results for a bad payload, so the caller fixes their data instead of silently dropping an id.

Lets a service principal undo a freshly-created account when its own outer transaction fails. Example flow: WACCA calls POST /api/v1/auth/register to provision a user, then its next onboarding step (e.g., creating a tenant row) fails — WACCA hits this endpoint to discard the account before the user discovers it exists.

Strict guardrails:

• Service-principal only. Human callers → 403. (Platform

admins use the existing 2-step POST /api/v1/admin/accounts/ {id}/hard-delete/prepare flow.)

• Time-boxed: only accounts younger than

APP__SECURITY__RECENT_DELETE_WINDOW_MINS (default 3) qualify. Older → 403 with the suggestion to use the admin flow. The window is enforced server-side from accounts.created_at.

• No reassignment. Within 3 minutes an account is normally

pristine; if it has already produced downstream state we won't silently undo (api_keys.created_by, invitations, service_accounts) the call returns 409 and the caller should NOT rollback — there's real downstream state.

• Personal-org sweep: the target's personal org (where it

is the lone owner) is deleted in the same transaction. A multi-member org owned by the target also returns 409.

Idempotency. Retrying on a target that no longer exists returns 404; treat that as "already rolled back" on the caller side.

Cascade. Account-side rows (sessions, audit_logs, memberships, password_reset_tokens, account_service_grants, api_keys[as resource]) cascade via the DB.

Audit log. An entry with action=DELETE, resource_type=ACCOUNT, actor_id=<calling service>, metadata.flow="transactional_rollback" is written best-effort (the delete commits regardless).

Rate limit: 10 / minute / IP (sensitive preset, fail-closed). 429 includes retry_after.

Errors:

• 403 / 4004 — caller is a human principal, OR account

exceeds the window.

• 404 — target does not exist (treat as already-deleted).
• 409 — target owns a multi-member org, or has FK-blocking

dependents (api_keys.created_by, invitations.invited_by, service_accounts.created_by_account_id) — rollback unsafe.

• 429 / 4008 — rate-limit exceeded.

Create a new human account. A personal organization is created in the same transaction with the registrant as owner. A verification email is queued (event email.requested). Auto-logs in: returns access + refresh tokens and sets the SSO refresh cookie. Rate limit: 3 / minute / IP.

Optional platform field (non-breaking). Shapes the verification email's links:

• omitted / any other value → web link only

https://account.ikavia.com/verify-email?token=…

• "wacca-mobile" → primary button is a wacca:// deeplink

(opens the mobile app) and the https:// link is still shown below as a clickable fallback for desktop.

Also accepts the spelling flatform (serde alias). Callers that omit it are unaffected.

Authenticate with email + password. Returns access + refresh tokens and the user's full organization list. Sets refresh + CSRF cookies. Brute-force protection: per-IP and per-account counters with progressive delay and lockout. Rate limit: 5 / minute / IP.

Exchange a Google ID token (the credential returned by the Google Identity Services button or One Tap) for our own access + refresh JWT pair. Response shape and cookies are identical to /auth/login, so a client can treat the two flows interchangeably.

Verification. The server validates the inbound JWT against Google's JWKS at https://www.googleapis.com/oauth2/v3/certs, checks iss ∈ {accounts.google.com, https://accounts.google.com}, aud == <APP__SECURITY__GOOGLE_OAUTH__CLIENT_ID>, and exp. The JWKS document is cached in Redis with TTL derived from Google's Cache-Control: max-age (fallback 1 h); a kid miss triggers a one-shot refresh.

Account resolution. Three branches, each surfaced to the client via the action field of the response so the FE can render the right copy without an extra round-trip:

1. By sub — token's sub already linked to an account (subsequent logins of a previously-linked Google identity). Response carries action: "logged_in". 2. By email — google_sub is empty but a row exists with this email. The row is auto-linked (Google has verified the address, so we trust the email match). If the row was still Pending it is promoted to Active in the same write. Response carries action: "linked" — the FE typically toasts "We connected your Google account to your existing profile" so the user understands what changed. 3. Auto-signup — no row matches sub or email. A new human account, personal organization, and the standard five system roles are created in one transaction. Email is marked verified at creation since Google already proved ownership. No password is set — the schema chk_human_must_have_auth is satisfied because google_sub is non-null. The user can add a password later via the change-password endpoint (which detects the NULL hash and skips the current-password check). Response carries action: "registered".

created_now is the legacy boolean form — equivalent to action == "registered" — kept for clients that integrated before action existed.

Errors:

• 503 — feature disabled (operator left

APP__SECURITY__GOOGLE_OAUTH__CLIENT_ID empty).

• 401 — token signature invalid, wrong audience, expired,

or email_verified: false from Google.

• 409 — account already linked to a DIFFERENT Google sub.

Rate limit: 5 / minute / IP (same bucket as /auth/login).

Exchange a Firebase Authentication ID token for our own access + refresh JWT pair. Mobile clients that already use Firebase Auth on the device (for Firestore rules, Functions, Crashlytics user binding, Remote Config personalisation, etc.) can send the Firebase-issued token here directly rather than juggling a separate raw Google token.

Verification. The server validates the inbound JWT against Firebase's JWKS at https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com, checks iss == https://securetoken.google.com/<APP__SECURITY__FIREBASE_AUTH__PROJECT_ID>, aud == <APP__SECURITY__FIREBASE_AUTH__PROJECT_ID>, and exp. The JWKS is cached in Redis under auth:firebase:jwks with TTL derived from Google's Cache-Control header.

Account resolution. Three branches, mirroring /auth/google. Each branch surfaces an action field in the response so the client can tell what actually happened:

1. By firebase_uid — token's sub already linked to an account. Fast path for returning users. Response carries action: "logged_in". 2. By email — auto-link an existing row (created via /auth/register or /auth/google or password) when the Firebase token's verified email matches. Promotes a Pending row to Active in the same write. Response carries action: "linked". 3. Auto-signup — fresh account + personal organization + 5 system roles. Response carries action: "registered".

created_now is the legacy boolean form — equivalent to action == "registered" — kept for clients that integrated before action existed.

Email required. Firebase Anonymous / custom-token sign-ins (no email) are rejected with 4003. If the mobile app needs anonymous flows, those will get a dedicated endpoint later.

Errors:

• 503 — feature disabled (operator left

APP__SECURITY__FIREBASE_AUTH__PROJECT_ID empty).

• 401 — token signature invalid, wrong audience, wrong

issuer, expired, no email, or email_verified: false.

• 409 — account already linked to a DIFFERENT Firebase

UID.

Rate limit: 5 / minute / IP (same bucket as /auth/login and /auth/google).

Stamps email_verified_at = NOW() on the target account without requiring the user to click the verification link sent at registration. Use only when identity has been confirmed out-of-band — for example, a user mistyped their email at signup and the team has since corrected it; an internal employee changed laptops and lost access to the original mailbox; a partner can't receive mail from the verification domain.

Behavior:

• Platform-admin only (* permission).
• Idempotent. Calling on an already-verified account

returns 200 with was_already_verified: true and does not bump updated_at.

• Rejects service accounts (no email) with 422.
• On change, emits an AccountUpdated event to the

account.events RabbitMQ exchange so downstream consumers see the new verified state.

Errors:

• 403 — caller lacks *.
• 404 — target account not found.
• 422 — target has no email (service account).

Audit: logged with admin_id, target_id, and the previous email_verified_at value (NULL on first verification).

Force-reset a user's password. Generates a temporary password per the deployment's policy, hashes it, persists with a TTL (login rejects the credential after expiry), and revokes every active session of the target. Audit-logged.

Authorization (strict per-org):

• Platform-admin (* permission): may reset any user.

X-Organization-Id is optional and used only as the audit log's organization context.

• Org owner / admin: MUST send X-Organization-Id; must

be owner or admin in that org; the target must be a member of the SAME org. Cross-org → 403.

• Self-reset is refused (use the normal change-password flow

or have another admin do it) so the audit log can't be silently rotated.

Delivery modes:

• delivery: "return" (default) — plaintext temp password is

returned in the response once. The admin is expected to hand it to the user out-of-band. A subsequent reset issues a fresh password; the prior one is discarded.

• delivery: "email" — account-service emails the user the

temp password with instructions. Response omits the plaintext.

Policy is configurable per deployment: APP__SECURITY__TEMP_PASSWORD__LENGTH (default 12) and APP__SECURITY__TEMP_PASSWORD__TTL_HOURS (default 72). The charset is fixed (upper+lower+digits+symbols, confusable characters removed).

Rate limit: 10 / minute / IP (fail-closed). 429 includes retry_after.

Errors:

• 400 / 4002 — delivery not return|email,

X-Organization-Id not a UUID.

• 403 / 4004 — caller not owner/admin in target org, or

target is not a member of target org, or admin attempted self-reset.

• 404 — target user_id does not exist.
• 422 — service account (no email/password) target,

X-Organization-Id required for non-platform admin and absent.

• 429 / 4008 — rate limit exceeded.

The legacy platform-admin-only endpoint POST /api/v1/admin/accounts/{account_id}/reset-password remains in place unchanged (default behaviour preserved).

Headers: Authorization: Bearer <admin-jwt>. Optional X-Organization-Id: <uuid> — REQUIRED for non-platform admins; optional (audit context only) for platform-admin. Sending it as anything but a UUID returns 422.

Step 1 of the two-step hard delete flow. Issues a short alphanumeric confirmation code scoped to (admin_id, target_account_id) and returns it to the admin UI. Code lives 5 minutes in Redis and is single-use.

> For service-driven rollback (the calling service just > created an account and its outer transaction failed): use > POST /api/v1/internal/accounts/{account_id}/hard-delete-recent > instead — it's service-principal-only, time-boxed by > APP__SECURITY__RECENT_DELETE_WINDOW_MINS (default 3 min), > and skips this two-step confirmation.

The UI's destructive-action modal displays this code and forces the admin to retype it before the actual delete is submitted to /hard-delete. Pure friction-against-fat- finger protection; the real authorization is the * permission check.

Pre-validates the target exists (404 if not) and that the admin is not targeting themselves (422). Each call replaces any previous code for the same (admin, target) pair — re-opening the modal generates a fresh code.

Rate limit: general per-IP cap. No specific bucket.

Step 2 of the hard delete flow. Verifies the confirmation_code against the value stashed by /prepare, then irreversibly removes the account row plus everything tied to it.

Cascade rules:

• audit_logs, sessions, api_keys (where the row's

account_id is the target), account_service_grants, password_reset_tokens, organization_memberships (target-side), service_accounts (target-side): removed automatically via existing ON DELETE CASCADE.

• Personal organization (target is owner AND only

active member): auto-deleted in the same transaction. Its memberships, roles, sessions and grants cascade via the FKs on organizations.id.

• Multi-member organization the target owns: blocks

the delete. Response is 409 with blocking_organizations listing each org's name, slug, and active member count. Admin must transfer ownership (or delete the org) before retrying.

• NOT-NULL FK columns without ON DELETE

(api_keys.created_by, invitations.invited_by, service_accounts.created_by_account_id): reassigned to the admin doing the delete so the rows stay valid. The audit-log entries covering the original creation events are gone, so use this knowing the "originally created by" attribution is lost.

Errors:

• 404 — target account not found (e.g. already deleted

in a parallel admin session).

• 422 — validation_failed: code mismatch, code

expired, or admin tried to delete themselves.

• 409 — blocking_organizations payload, see above.
• 5xx — DB transaction failure; nothing was committed.

Exchange a refresh token for a new access + refresh pair. The old refresh token's hash is rotated server-side; the old JTI is added to the revocation list once rotation is persisted. Replaying the old refresh token after this call kills the session (reuse detection). Refresh token may be in the body or in the refresh_token cookie (SSO flow).

Revoke the current session. The access token's JTI is also added to the revocation list so a token stolen before logout stops validating immediately. Cookies are always cleared on the response, even if the server-side revoke fails. Service principals cannot call this endpoint — they have no session.

Revoke every active session for the calling account. Useful for "I lost my phone" or post-password-change cleanups. Cookies are rotated/cleared on the response.

Re-emit the verification email for an unverified account. The response is deliberately indistinguishable from the "email not found" case so a caller can't enumerate which addresses have an account — both return 200 with the same generic message. A verified account also returns 200 (and quietly does nothing).

The FE surface for this endpoint is the Verify-email banner mounted in the dashboard layout (components/layout/verify-email-banner.tsx): a sticky yellow strip that shows for any user with email_verified=false and carries a "Resend email" button. Calling the endpoint manually is the path for unauthenticated callers (e.g. a "Didn't get the email?" link before sign-in).

Rate limit: 3 / minute / IP.

Initiate a password reset. Always returns success, even when the email is unknown, to prevent email enumeration. Generates a 1-hour JWT and emits an email.requested event with the reset link.

Optional platform field (non-breaking). Controls the scheme of the reset link in the emailed message:

• omitted / any other value → web link

https://account.ikavia.com/reset-password?token=…

• "wacca-mobile" → custom-scheme deeplink

wacca://account.ikavia.com/reset-password?token=… so the mobile OS opens the app instead of a browser.

The field also accepts the spelling flatform (serde alias) so the mobile client can send either key. Existing callers that send only email are unaffected.

Complete a password reset using the JWT from the email link. Validates the token (signature + jti not previously used), updates the password hash, and revokes all sessions for the account.

Introspect an access token (signature + exp + revocation). Used by downstream services that prefer a server-side check over local public-key verification. Returns the claims as-is: permissions come from the token, not re-derived from current state. Use /auth/refresh if you need fresh permissions. Rate limit: 100 / minute / IP.

Return the principal identity carried by the request — exactly what the middleware extracted, with no extra DB lookups. Useful for SDKs and gateways debugging auth wiring.

Return the RS256 public key (PEM) for local JWT verification by downstream services. Cache this for the lifetime of expires_at (default 90 days).

Key rotation strategy:

• Each issued JWT carries a kid claim in its header naming the

key that signed it (e.g. key-2026-03-01-v1).

• Verifiers should cache by kid. On a cache miss (unfamiliar

kid), re-fetch this endpoint to learn the new key.

• During rotation, account-service serves the new key here

but continues to accept tokens signed by the previous key until those tokens naturally exp. Verifiers should retain the previous key entry until its tokens have aged out.

• expires_at is the rough cache horizon — refresh before that

even without a kid mismatch to pick up scheduled rotations.

Validate the supplied X-API-Key header and return a 1-hour service JWT (principal_type: service). Lets a service principal authenticate downstream calls with a verifiable JWT instead of re-presenting the API key on every hop. The JWT carries the service account's capabilities as permissions and nil as sid.

Network-reachable counterpart to the gRPC grant-management flow. A System account (basic-auth credential issued by a platform admin for a headless peer backend — distinct from an org-owned service account) swaps its credentials for a short-lived RS256 service JWT (principal_type: service).

Pick which token-mint endpoint based on the caller principal:

Both endpoints return the same JWT shape — same issuer, kid, RS256 key, principal_type: service. Peer services verify either token through the same JWKS / /auth/public-key path without any code change. The difference is who's calling and how their credentials are managed: service accounts are managed inside an organization, System accounts are managed by the platform admin under /admin/system-accounts.

The token is byte-for-byte compatible with every other token this service mints (same issuer, kid, RS256 key), so peer services (e.g. Media Service) verify it through their existing public-key / JWKS path with no change to their validation.

Permissions are admin-granted, never caller-chosen. The token's permissions come solely from the System account's token_permissions grant (set via the admin POST /api/v1/admin/system-accounts/{id}/permissions endpoint), e.g. ["media:upload"]. The request body carries no permission input. sub is the System account id; org_id is absent (System accounts have no organization); sid is nil.

TTL follows the access-token policy (APP__SECURITY__JWT__ACCESS_TOKEN_TTL_MINS, default 15 min).

Auth: Authorization: Basic base64(name:password). 401 for missing/invalid credentials (neutral body — never reveals whether a name exists); 403 once the password is correct but the System account is revoked.

Issue a service-grant for account_id. Idempotent — calling with the same (account_id, service, organization_id) tuple returns granted_now=false and the existing granted_at.

Scope.

• Empty organization_id ⇒ global grant. Visible in the

holder's JWT in every org context.

• Non-empty organization_id ⇒ org-scoped grant. Only

contributes to the JWT when the holder's current org matches.

JWT emission. Granting a service whose key is not in the built-in list (email, planner, survey, media, platform_admin) results in {service}:* being added to the holder's JWT permissions array on next token issuance. Granting wacca-tenant produces wacca-tenant:*.

Errors:

• UNAUTHENTICATED — no authorization metadata, wrong

scheme, unknown user, or wrong password.

• PERMISSION_DENIED — service not covered by the

caller's prefix allowlist.

• INVALID_ARGUMENT — account_id / organization_id not

a UUID, or service empty.

Revoke a previously-issued grant. Idempotent — calling on a tuple that doesn't exist returns revoked=false. The scope (organization_id empty vs. non-empty) must match the row to be revoked; revoking a global grant with an organization_id set is a no-op.

Errors: Same set as GrantService. Notably, a caller can only revoke what they could grant — revoking platform_admin from wacca's credential is PERMISSION_DENIED, not silent success.

Enumerate the grants account_id holds within the caller's allowlist. Grants outside the allowlist (other services' keys, platform_admin) are filtered out — wacca cannot use this to map who else has what.

service_prefix further narrows the result. If non-empty, the prefix must itself be allowed for the caller, otherwise PERMISSION_DENIED.

Look up an account by id. Returns the public-mirror fields a sibling service usually wants for display / authorization: account_id, account_type ("human" | "service"), display_name, email (empty string for service accounts with no email), status, created_at (unix seconds).

A soft-deleted row (deleted_at IS NOT NULL) answers NOT_FOUND — the row is logically gone for caller purposes.

Errors:

• UNAUTHENTICATED — no authorization metadata, wrong

scheme, unknown user, or wrong password.

• INVALID_ARGUMENT — account_id is not a UUID.
• NOT_FOUND — no live row matches the id.

Cheap existence probe. Use this when the caller only needs to confirm an account_id resolves (e.g., precondition before storing a foreign key) and doesn't need the rest of the account row. Same lookup semantics as GetAccount: the underlying repo filters WHERE deleted_at IS NULL, so both soft-deleted AND deactivated rows answer exists=false (deactivate sets deleted_at alongside status='deactivated', so the two states are colinear in practice — there is no reachable row with deleted_at IS NULL AND status='deactivated').

status carries the account's status string only when exists=true (empty string otherwise). In practice the values you'll see are "active" or "pending" — every row that's reached deactivated is also soft-deleted, and the probe returns false before it can surface that status.

Errors:

• UNAUTHENTICATED — see GetAccount.
• INVALID_ARGUMENT — account_id is not a UUID.

Cheap probe: is the account's email verified?

Use when a sibling service needs to gate on "email- verified user" before issuing some capability (sending a notification to the address, marking a profile public, allowing high-trust action) and wants a single boolean answer without fetching the full profile.

Response shape — two booleans:

• verified — true iff the account exists, is live

(not soft-deleted), AND its email is verified. False covers four cases at once: unknown id, soft-deleted row, account has no email (some service accounts), email not yet verified. For most callers a single check on verified is sufficient: all four cases mean "do not trust this email".

• account_exists — true iff a live row matches

account_id, regardless of verification state. Lets a caller distinguish "no such user" from "user exists but unverified" when that matters (e.g. distinct error message in a UI).

Same WHERE deleted_at IS NULL filter as the other reads on this service — soft-deleted / deactivated rows resolve to verified=false, account_exists=false.

Errors:

• UNAUTHENTICATED — see GetAccount.
• INVALID_ARGUMENT — account_id is not a UUID.

Slim single-account resolver. Same lookup semantics as GetAccount (soft-deleted / deactivated → NOT_FOUND), but returns only the public-display projection: {id, display_name, email, avatar_media_id, phone_number}.

Use this for non-hot resolve paths — replica backfill on cache miss, daily reconciliation. Don't reach for GetAccount if you only need display fields; the slim projection is the stable replica contract.

Empty string conventions on proto3:

• email = "" when the row has no email (some service

accounts) — treat as absent, not literal.

• avatar_media_id = "" when unset.
• phone_number = "" when unset.

Errors:

• UNAUTHENTICATED — see GetAccount.
• INVALID_ARGUMENT — account_id is not a UUID.
• NOT_FOUND — no live row matches the id.
• RESOURCE_EXHAUSTED — id-resolver rate-limit tripped.

Batch resolve by account id. Server caps the slice length at APP__SECURITY__INTERNAL_LOOKUP__BATCH_CAP_IDS (default 100); going over → INVALID_ARGUMENT. The server also dedups the id slice before hitting the repo, so repeated ids in the request don't double-charge the backend or appear twice in the response.

Behaviour matches REST POST /accounts/bulk-lookup:

• Missing ids (no live row) are silently OMITTED — diff

against the request slice to detect gaps.

• Order of accounts is NOT meaningful.
• Soft-deleted / deactivated rows are NOT returned.

Errors:

• UNAUTHENTICATED — see GetAccount.
• INVALID_ARGUMENT — any element fails UUID parse, OR

slice length > the configured cap.

• RESOURCE_EXHAUSTED — id-resolver rate-limit tripped.

Batch resolve by email. The email VO stores canonicalized lowercase, so matching is exact case-insensitive — no fuzzy, no substring, no domain wildcards.

Tighter batch cap and tighter rate-limit bucket than the id resolver because email lookup is a higher enumeration risk surface. Defaults:

• Batch cap 50 (APP__SECURITY__INTERNAL_LOOKUP__BATCH_CAP_EMAILS).
• Rate limit 120/min/system-account

(__RATE_LIMIT_PER_MIN_EMAILS).

The server normalises every input (trim + lowercase) and dedups before hitting the repo. Empty-after-trim entries are dropped silently. A malformed address in the slice rejects the WHOLE batch (caller bug — chunk + retry won't recover; fix the input).

Missing emails (no live row) are silently omitted — same pattern as the id resolver. Diff against the input slice.

Soft-deleted / deactivated rows are NOT returned. The surface is service-principal only — this is NOT a public email-existence oracle.

Errors:

• UNAUTHENTICATED — see GetAccount.
• INVALID_ARGUMENT — any element fails email parse, OR

slice length > the configured cap.

• RESOURCE_EXHAUSTED — email-resolver rate-limit tripped.

Verify a user's plaintext password against the stored argon2 hash. Account is identified by UUID only (no email lookup — keeps the RPC from doubling as an email enumeration probe).

Response shape:

• valid=true — argon2 matched. account_status carries

the row's status string ("active" / "pending" / "suspended"), so the caller can decide whether to proceed (e.g., refuse step-up auth on a "suspended" account even though the password was right).

• valid=false — password didn't match, OR the account

is soft-deleted, OR the account has no password set (SSO-only). account_status is empty so a caller can't probe state by toggling the password input.

Soft-deleted / unknown accounts short-circuit before argon2 runs, so the response time can't be used to probe state-of-existence via timing.

Errors:

• UNAUTHENTICATED — missing / invalid system-account

Basic credential.

• INVALID_ARGUMENT — account_id not a UUID, or

password empty.

• RESOURCE_EXHAUSTED — the shared brute-force counter

for this account_id has tripped; retry after the cooldown encoded in the status message.

All rows ordered by created_at desc, including revoked rows (greyed out in the UI). Hash and prefix allowlist are returned because the admin who sees this page already has full platform access; not exposing the hash wouldn't add security but would prevent the UI from showing whether a recent rotate succeeded.

Creates a new credential and returns the plaintext password ONCE in the response. The hash is the only persisted form.

Validation:

• name: ASCII letters, digits, -, or _. Unique

across active AND revoked rows (you cannot re-use a name once revoked).

• allowed_prefixes: at least one non-empty entry.
• description: optional free-text.

Errors:

• 409 — name already exists (active or revoked).
• 422 — validation failure on name or prefixes.

Replace the token_permissions array on an active system account, without touching the password. Used to grant (or rescind) capabilities such as media:upload consumed by the /auth/system-token bearer-token flow.

Server-side normalisation: each entry is trimmed; empty entries are dropped; duplicates are folded while preserving first-seen order. Send [] to clear all permissions.

Cache discipline. Bearer-token minting reads token_permissions directly from Postgres on every call (the gRPC Redis cache deliberately omits this column), so a new grant takes effect on the next token mint. Tokens already in flight keep the permissions they were issued with until they expire (≤ access-token TTL, default 15 min).

Errors:

• 403 — caller is not a platform admin.
• 404 — id unknown or row is revoked (revoked rows

cannot be re-permissioned; rotate or create fresh).

• 422 — token_permissions field missing from body.

Generates a fresh 32-character password and replaces the stored hash atomically. Old password stops working on the next gRPC call (Redis cache is invalidated as part of the same handler).

Cannot be called on a revoked row — use Create with a fresh name instead. Returns 422 in that case.

Flips status to revoked, stamps revoked_at and revoked_by_account_id. Idempotent — the response includes already_revoked: true if the row was already revoked. The row is never hard-deleted so the audit trail (when issued, by whom, when revoked) stays intact.

Lightweight liveness check. Returns 200 with a small JSON when the process is up. Does not touch DB / Redis / RabbitMQ — use /health/detailed for that. Suitable for k8s livenessProbe.

Per-dependency health snapshot. Probes Postgres, Redis, and RabbitMQ and returns each dependency's state. A degraded dependency yields HTTP 503 so a load balancer can drop the pod from rotation. Heavier than /health — call from readinessProbe, not livenessProbe.

Prometheus exposition format. Includes HTTP request counters / latency histograms (sanitized path labels — id segments collapsed to :id so cardinality stays bounded), gRPC counters, brute-force counters, rate-limiter counters, and Redis connection pool stats. Should be firewalled to the metrics-collector subnet, not exposed publicly.

Lightweight existence + display info for an organization. Used by frontends to validate org-scoped invitation links before login. Returns minimal data — no member or role info is leaked.

List organizations the authenticated principal is a member of. Each entry includes the principal's role in that org.

Create a new organization with the caller as owner. Slug is auto-derived from the name when omitted; if the slug collides a 4xx is returned and the caller should retry with an explicit slug.

Fetch a single organization by id. Caller must be a member.

Update the organization's name or slug.

Soft-delete (archive) an organization. Owner-only — protected by the owner role's * wildcard rather than a per-action permission. Members lose access on next token rotation; all sessions remain intact for other orgs the user belongs to.

Issue a new token pair bound to a different organization. The existing session id is reused, so refresh continuity is preserved. The caller must already be a member of the target org.

Remove the caller's own membership. Owners cannot leave — transfer ownership first or delete the organization.

Paged member list with role + permissions.

Send an invitation to an email address. If a role is omitted the org's default-member role is assigned on accept. The recipient gets an email via the email.requested event.

Remove a member from the org. Cannot remove the owner.

Reassign a member to a different role. New role takes effect on their next token rotation.

List roles defined in the org (system + custom).

Create a custom role. Permissions are free-form strings (the permission service interprets them); see the Permissions section for the canonical names used by account-service itself.

Fetch a single role.

Patch a role. System roles (e.g. owner) are read-only.

Delete a custom role. Fails if any member is currently assigned to it — reassign them first. System roles cannot be deleted.

Org-wide audit feed. Same shape as /me/activities but scoped to all actors within the organization. Requires audit_logs:read permission in the org.

Read the full lock row including audit columns. Used by the superadmin UI at /dashboard/admin-registration.

Toggle the lock and optionally set a custom message. Idempotent — calling with the same (enabled, message) twice is a no-op.

Body fields:

• enabled (bool, required) — true blocks, false

opens.

• message (string, optional) — shown to users on the

register page when locked. Omit or send empty string to clear and let the FE use its default copy.

Returns the new state; Redis cache is invalidated as part of the handler so the change is observable on the next request.

Public read of the current lock state. No auth required — the register page calls this on first render so it can show the banner instead of letting the user fill out a form that's going to 423.

Only two fields are returned (locked, message); the audit columns stay private. Backed by the same 5-minute Redis cache as the gate check.

List requests filtered by status. Pagination is intentionally omitted — queue depth is expected to stay small under realistic emergency conditions.

Mark a pending request approved + mint a 24-hour approval token. The plaintext token is returned ONCE in data.approval_url; share it with the user out-of-band (chat, manual email) until the email-event automation lands.

Errors:

• 404 — request not found.
• 422 — request is not in pending (already

approved/rejected/completed).

Mark a pending request rejected. No notification is sent to the user automatically (intentional — guards against probe-and-confirm by attackers).

Public endpoint — the approval token IS the auth. Consume the token, set the password, create the account, auto-login. Same response shape as /auth/register so the FE can treat completion as a normal "you're logged in now".

Errors:

• 422 — token missing/invalid/expired, or password

too short (< 8 chars).

• 429 — rate-limit (3/min/IP, same as register).

Phase A limitation. SSO-source requests return 422 here — only email_password source is finalised by this endpoint for now.