{ "schemes": [], "swagger": "2.0", "info": { "description": "Identity & authorization platform — auth, accounts, tenants, groups, connections, devices, passkeys, invites, terms, telemetry, and the audit log.", "title": "enforcer-v3 API", "contact": {}, "version": "1.0" }, "host": "", "basePath": "/api/v1/enforcer", "paths": { "/accounts": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Every account row the caller may read, newest-name-first by default: admin sees all tenants, tenant_admin and developer see their own tenant, a plain user sees only themselves — the same compiled row filter GET /accounts/summary uses, so a summary tile and the list it drills into always agree on which rows count. All query filters intersect (AND). since/until run on accounts.created_at and are parsed by the same window parser /accounts/summary uses, so the formats and error codes cannot drift between the two endpoints.", "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "List", "operationId": "listAccounts", "parameters": [ { "type": "string", "description": "free-text search", "name": "q", "in": "query" }, { "type": "string", "description": "exact email match", "name": "email", "in": "query" }, { "type": "boolean", "description": "filter by active flag", "name": "active", "in": "query" }, { "type": "boolean", "description": "true = verified emails only, false = unverified only; absent = no filter", "name": "email_verified", "in": "query" }, { "type": "boolean", "description": "true = missing first or last name, false = complete profiles only; absent = no filter", "name": "profile_incomplete", "in": "query" }, { "type": "boolean", "description": "admin-set provisioner flag (PATCH /accounts/:id/profile-completed): true = marked complete, false = awaiting review; absent = no filter. NOT the same as profile_incomplete, which derives from name data", "name": "profile_completed", "in": "query" }, { "type": "string", "description": "accounts with a verified session from this provider (e.g. persona)", "name": "verified_provider", "in": "query" }, { "enum": [ "verified", "pending", "failed", "none" ], "type": "string", "description": "KYC rollup bucket, same precedence as /accounts/summary?group_by=verification_status", "name": "verification_status", "in": "query" }, { "enum": [ "admin", "tenant_admin", "developer", "user" ], "type": "string", "description": "role slug, same buckets as group_by=role", "name": "role", "in": "query" }, { "type": "boolean", "description": "true = has at least one wallet, false = none", "name": "has_wallet", "in": "query" }, { "type": "boolean", "description": "true = a phone on the linked person, false = none", "name": "has_phone", "in": "query" }, { "type": "boolean", "description": "true = invited by anyone, false = organic signup", "name": "invited", "in": "query" }, { "type": "boolean", "description": "only accounts I invited", "name": "invited_by_me", "in": "query" }, { "type": "string", "format": "uuid", "description": "only accounts invited by this account id (admin invitee tracking; row-level authz still applies)", "name": "invited_by", "in": "query" }, { "type": "string", "format": "uuid", "description": "restrict to this tenant (row-level authz still applies: a non-admin sees only their own)", "name": "tenant_id", "in": "query" }, { "type": "string", "format": "uuid", "description": "only members of this group", "name": "group_id", "in": "query" }, { "type": "string", "format": "uuid", "description": "exclude members of this group", "name": "exclude_group_id", "in": "query" }, { "type": "string", "format": "date-time", "description": "created at or after this instant (RFC3339) — same param as /accounts/summary", "name": "since", "in": "query" }, { "type": "string", "format": "date-time", "description": "created before this instant (RFC3339) — same param as /accounts/summary", "name": "until", "in": "query" }, { "type": "string", "format": "date-time", "description": "last active at or after this instant (RFC3339); never-active accounts never match", "name": "last_active_since", "in": "query" }, { "enum": [ "name", "name_desc", "recent", "oldest", "active" ], "type": "string", "default": "name", "description": "sort order", "name": "sort", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AccountPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/bulk/activate": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Sets active=true on every id in the body, applying the SAME per-target authorization (ResourceAuth manage, so a tenant_admin can only touch accounts in their own tenant) and the same admin-role-escalation fence as the single-account PUT /accounts/{id}/active. Never all-or-nothing: each id is authorized and applied independently, and the response reports succeeded/failed counts plus a per-id ok|forbidden|error result rather than aborting the batch on the first failure.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Bulk activate", "operationId": "bulkActivateAccounts", "parameters": [ { "description": "account ids", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.IDsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.BulkResultResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/bulk/deactivate": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Sets active=false on every id in the body — the deactivation twin of bulkActivateAccounts, with the identical per-target authorization, escalation fence, and partial-failure reporting (succeeded/failed counts plus a per-id ok|forbidden|error result). Deactivating does not touch sessions or API keys; combine with bulkInvalidateAccountSessions to force those accounts out immediately.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Bulk deactivate", "operationId": "bulkDeactivateAccounts", "parameters": [ { "description": "account ids", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.IDsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.BulkResultResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/bulk/delete": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "IRREVERSIBLE. Hard-deletes every id in the body via the same cascade as DELETE /accounts/{id} (Privy user removal, session/key/link revocation, PII scrub, soft-delete) — not a bulk deactivation. Per-target ResourceAuth manage is enforced independently for each id (a tenant_admin can only delete within their own tenant); the response reports succeeded/failed counts and a per-id ok|forbidden|error result, so a partially-authorized batch still deletes everything it was allowed to.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Bulk delete", "operationId": "bulkDeleteAccounts", "parameters": [ { "description": "account ids", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.IDsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.BulkResultResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/bulk/invalidate-sessions": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Bulk invalidate sessions (force logout)", "operationId": "bulkInvalidateAccountSessions", "parameters": [ { "description": "account ids", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.IDsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.BulkResultResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/search": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Typo-tolerant identity search over username, first/last name, email and phone, ranked by pg_trgm trigram similarity. Matches when EITHER the similarity operator fires (typo tolerance, governed by pg_trgm.similarity_threshold) OR q is a plain substring of the haystack OR q exactly equals the account's Privy DID. Row visibility is the identical compiled authz filter GET /accounts uses, so this endpoint cannot surface anything the plain list would hide. Cross-tenant callers (admin) MUST pass tenant_id — omitting it is a 400 tenant_required, never a silent union of every tenant's accounts. Tenant-scoped callers may pass their own tenant_id or omit it.", "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Fuzzy search", "operationId": "searchAccounts", "parameters": [ { "type": "string", "description": "search text (min 2 chars) — username, name, email, phone, or an exact privy DID", "name": "q", "in": "query", "required": true }, { "type": "string", "format": "uuid", "description": "scope to ONE tenant. Required for cross-tenant callers (admin) — without it the search is a 400, never a silent union of every tenant. Tenant-scoped callers may pass their own tenant or omit it.", "name": "tenant_id", "in": "query" }, { "type": "boolean", "description": "true = KYC-verified accounts only; false = everything not verified (same bucket predicate as /accounts?verification_status=)", "name": "verified", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AccountSearchResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/summary": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Aggregate counts over the SAME compiled row filter GET /accounts uses, so a tenant admin's summary counts only their tenant and a user's counts only themselves — never a number the list endpoint would refuse to show as rows. group_by buckets into a closed, documented dimension set (an unknown group_by is a 400, not a silent no-op); interval instead (or alongside) produces a time-bucketed data.series over the same since/until window GET /accounts filters on.", "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Summary", "operationId": "summarizeAccounts", "parameters": [ { "enum": [ "role", "active", "email_verified", "profile_complete", "verification_status", "has_wallet", "invited", "tenant", "verified_provider", "group" ], "type": "string", "description": "bucket dimension; every bucket has a matching GET /accounts filter", "name": "group_by", "in": "query" }, { "type": "string", "format": "date-time", "description": "RFC3339 lower bound on created_at (inclusive)", "name": "since", "in": "query" }, { "type": "string", "format": "date-time", "description": "RFC3339 upper bound on created_at (exclusive)", "name": "until", "in": "query" }, { "enum": [ "hour", "day", "week", "month" ], "type": "string", "description": "returns data.series bucketed at this interval", "name": "interval", "in": "query" }, { "type": "string", "description": "IANA time zone for bucketing (default UTC)", "name": "tz", "in": "query" }, { "type": "string", "description": "free-text search", "name": "q", "in": "query" }, { "type": "string", "description": "exact email match", "name": "email", "in": "query" }, { "type": "boolean", "description": "filter by active flag", "name": "active", "in": "query" }, { "type": "boolean", "description": "true = verified emails only, false = unverified only; absent = no filter", "name": "email_verified", "in": "query" }, { "type": "boolean", "description": "true = missing first or last name, false = complete profiles only; absent = no filter", "name": "profile_incomplete", "in": "query" }, { "type": "boolean", "description": "admin-set provisioner flag (PATCH /accounts/:id/profile-completed): true = marked complete, false = awaiting review; absent = no filter. NOT the same as profile_incomplete, which derives from name data", "name": "profile_completed", "in": "query" }, { "type": "string", "description": "accounts with a verified session from this provider (e.g. persona)", "name": "verified_provider", "in": "query" }, { "enum": [ "verified", "pending", "failed", "none" ], "type": "string", "description": "KYC rollup bucket", "name": "verification_status", "in": "query" }, { "enum": [ "admin", "tenant_admin", "developer", "user" ], "type": "string", "description": "role slug", "name": "role", "in": "query" }, { "type": "boolean", "description": "true = has at least one wallet, false = none", "name": "has_wallet", "in": "query" }, { "type": "boolean", "description": "true = a phone on the linked person, false = none", "name": "has_phone", "in": "query" }, { "type": "boolean", "description": "true = invited by anyone, false = organic signup", "name": "invited", "in": "query" }, { "type": "string", "format": "uuid", "description": "only accounts invited by this account id", "name": "invited_by", "in": "query" }, { "type": "boolean", "description": "only accounts I invited", "name": "invited_by_me", "in": "query" }, { "type": "string", "format": "uuid", "description": "restrict to this tenant (row-level authz still applies)", "name": "tenant_id", "in": "query" }, { "type": "string", "format": "uuid", "description": "only members of this group", "name": "group_id", "in": "query" }, { "type": "string", "format": "uuid", "description": "exclude members of this group", "name": "exclude_group_id", "in": "query" }, { "type": "string", "format": "date-time", "description": "last active at or after this instant (RFC3339)", "name": "last_active_since", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Response" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One account by id (ResourceAuth read — visible to the account itself, its tenant admins, and platform admins). 404 account_not_found for an unknown or out-of-scope id; the endpoint is not an existence oracle for ids outside the caller's authorized scope.", "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Get", "operationId": "getAccount", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AccountResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Hard-deletes an account (ResourceAuth manage — admin or tenant_admin only): best-effort removes the upstream Privy user, revokes sessions/API keys/links, scrubs PII, then soft-deletes the row. Irreversible from the API's perspective. For a reversible block use PUT /accounts/{id}/active with active=false instead.", "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Delete", "operationId": "deleteAccount", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Update account profile", "operationId": "updateAccountProfile", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_accounts.ProfileInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AccountResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/{id}/active": { "put": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Flips one account's active flag (ResourceAuth manage). The reversible counterpart to DELETE /accounts/{id}: setting active=false blocks the account without removing data, upstream identity, or history. Returns 403 forbidden if the caller would be escalating an admin account's access, the same fence bulkActivateAccounts/bulkDeactivateAccounts enforce per-target.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Set Active", "operationId": "setAccountActive", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "active flag", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SetActiveRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AccountResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/{id}/passkey-mfa": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Passkey MFA status for an account", "operationId": "getAccountPasskeyMfaStatus", "parameters": [ { "type": "string", "description": "account id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PasskeyMfaStatusResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/{id}/phone-risk": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Twilio Lookup v2 risk for an account's phone. Self for any authed user; tenant_admin/admin/developer for any account.", "produces": [ "application/json" ], "tags": [ "phone-risk" ], "summary": "Account phone risk", "operationId": "getAccountPhoneRisk", "parameters": [ { "type": "string", "description": "account id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PhoneRiskResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/{id}/profile-completed": { "put": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Set Profile Completed", "operationId": "setAccountProfileCompleted", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "profile-completed flag", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SetProfileCompletedRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AccountResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/{id}/role": { "put": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Assigns a role slug to one account (ResourceAuth manage). Rejects with 403 forbidden if the change would escalate an account to admin beyond what the caller may grant, and with 400 unknown_role if the slug does not exist as a role in scope. Role changes take effect immediately — role is read fresh from the account row on every request, never trusted from an old JWT claim.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Set Role", "operationId": "setAccountRole", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "role assignment", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SetRoleRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AccountResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/accounts/{id}/sessions": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "List Account Sessions", "operationId": "listAccountSessions", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AdminSessionListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Revoke Account Sessions", "operationId": "revokeAccountSessions", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RevokedSessionsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/auth-events": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Auth-funnel events for one tenant, newest first — including the attempts that never reached an account, which is the whole point. Pass email to answer \"did this address ever try, and what failed\": the address is hashed server-side and matched against the stored hash, so the search term is never written to the database and the plaintext never had to be stored to be findable. Scoped to the caller's tenant; only a cross-tenant admin may name another via tenant_id. from/to accept RFC3339 or YYYY-MM-DD. Unknown query parameters are a 400, not a silently unfiltered list.", "produces": [ "application/json" ], "tags": [ "admin" ], "summary": "List pre-auth attempts", "operationId": "adminListAuthAttempts", "parameters": [ { "type": "string", "description": "tenant (cross-tenant admin only)", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "exact address to search for (hashed server-side)", "name": "email", "in": "query" }, { "enum": [ "otp_requested", "otp_send_failed", "otp_verify_failed", "login_failed" ], "type": "string", "description": "one of the closed set", "name": "event", "in": "query" }, { "type": "string", "description": "RFC3339 or YYYY-MM-DD", "name": "from", "in": "query" }, { "type": "string", "description": "RFC3339 or YYYY-MM-DD", "name": "to", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthAttemptListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/client-events": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Client telemetry across every tenant the caller may see (admin: all; everyone else: their own), optionally narrowed with tenant_id. A non-admin passing a FOREIGN tenant_id gets 403 rather than being silently shown their own tenant's feed. source is a CSV of event sources (e.g. plaid_link,bank_link_exchange,plaid_refresh_patch,external_bank_unlink,bank_link_funnel); session_id matches either the server-stamped session_id or an external_session_id (e.g. a Privy sid).", "produces": [ "application/json" ], "tags": [ "telemetry" ], "summary": "Feed", "operationId": "adminListClientEvents", "parameters": [ { "type": "string", "description": "filter by tenant", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "CSV of telemetry sources to filter (e.g. plaid_link,bank_link_exchange)", "name": "source", "in": "query" }, { "type": "string", "description": "single event filter, e.g. EXIT", "name": "event", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" }, { "type": "string", "description": "one session's events — matches the server-stamped session_id OR external_session_id (e.g. a Privy sid)", "name": "session_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ClientEventListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/client-events/summary": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Aggregated client telemetry: totals, per-dimension buckets (group_by=source|event|tenant — tenant requires the platform-admin grant, since it degenerates to one bar for anyone else), and an optional time series bucketed at interval (hour|day|week|month) in the tz IANA zone (default UTC). Uses the SAME row scope and filter vocabulary as adminListClientEvents, so every tile has a drill-down list covering exactly the rows it counted.", "produces": [ "application/json" ], "tags": [ "telemetry" ], "summary": "Client-events summary", "operationId": "getClientEventsSummary", "parameters": [ { "type": "string", "description": "source | event | tenant (tenant requires platform admin)", "name": "group_by", "in": "query" }, { "type": "string", "description": "narrow to one tenant; non-admins may only name their own", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "CSV of sources, e.g. plaid_link,bank_link_exchange — the bank-link chart is this filter", "name": "source", "in": "query" }, { "type": "string", "description": "exact event, e.g. HTTP_5XX", "name": "event", "in": "query" }, { "type": "string", "description": "one account's events", "name": "account_id", "in": "query" }, { "type": "string", "description": "one session's events — matches the server-stamped session_id OR external_session_id (e.g. a Privy sid)", "name": "session_id", "in": "query" }, { "type": "string", "description": "RFC3339 lower bound (clamped by the retention window)", "name": "since", "in": "query" }, { "type": "string", "description": "RFC3339 upper bound (exclusive)", "name": "until", "in": "query" }, { "type": "string", "description": "hour | day | week | month — returns data.series bucketed at this interval", "name": "interval", "in": "query" }, { "type": "string", "description": "IANA time zone for bucketing (default UTC)", "name": "tz", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Response" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/email-dlq": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The email dead-letter queue: messages that failed delivery and were parked rather than lost, newest first. Optional topic filter is a case-insensitive substring match on the wire topic. Pair with replayEmailDlqEntry to resend one or deleteEmailDlqEntry to drop it.", "produces": [ "application/json" ], "tags": [ "email-dlq" ], "summary": "List", "operationId": "listEmailDlq", "parameters": [ { "type": "string", "description": "filter by wire topic (case-insensitive substring)", "name": "topic", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DLQEntryListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/email-dlq/{id}": { "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Acknowledge and drop a parked message WITHOUT replaying it — use when the send is known to be no longer wanted. System-admin gated; 404 dlq_entry_not_found if the id is unknown.", "produces": [ "application/json" ], "tags": [ "email-dlq" ], "summary": "Delete", "operationId": "deleteEmailDlqEntry", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/email-dlq/{id}/replay": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "email-dlq" ], "summary": "Replay DLQ entry", "operationId": "replayEmailDlqEntry", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/fulfillments": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The CS failed-P2P dashboard: fulfillments across the tenant. Party scope is OPTIONAL: `user_id` matches EITHER side (sender, receiver or creator), while `sender_user_id` / `receiver_user_id` pin one end. All supplied filters intersect, so sender+receiver together mean \"from A to B\". Without them the list is tenant-wide and only pageable. `status` = closed (cancelled|declined|expired — the failed set), outstanding (pending|claimed|submitted), all, or an exact status. A system admin may pass ?tenant_id to view another tenant; tenant-scoped callers (tenant_admin, developer) are pinned to their own. total matches the rows' filter.", "produces": [ "application/json" ], "tags": [ "fulfillment" ], "summary": "Failed / all P2P fulfillments, tenant-wide (admin)", "operationId": "adminTenantFulfillments", "parameters": [ { "type": "string", "description": "closed|outstanding|all|\u003cexact\u003e (default all)", "name": "status", "in": "query" }, { "enum": [ "recent", "oldest" ], "type": "string", "description": "recent (newest first, default) | oldest", "name": "sort", "in": "query" }, { "type": "string", "description": "view another tenant (admin only)", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "scope to one person on EITHER side (sender, receiver or creator)", "name": "user_id", "in": "query" }, { "type": "string", "description": "scope to transfers SENT by this user", "name": "sender_user_id", "in": "query" }, { "type": "string", "description": "scope to transfers RECEIVED by this user", "name": "receiver_user_id", "in": "query" }, { "type": "string", "description": "reference starts with this literal prefix (e.g. RWD:\u003cgroup_id\u003e:) — payout-campaign rows", "name": "reference_prefix", "in": "query" }, { "type": "string", "description": "sugar for reference_prefix=RWD:\u003cgroup_id\u003e: — everything fanned out from this payout group", "name": "group_id", "in": "query" }, { "enum": [ "p2p", "deposit", "billpay", "direct", "reward", "terminal" ], "type": "string", "description": "p2p (no machine tag — a real person-to-person transfer) | deposit (DEPOSIT:) | billpay (BP:) | direct (DIRECT:) | reward (RWD:) | terminal (TERMINAL: — a POS sale)", "name": "kind", "in": "query" }, { "enum": [ "include", "exclude", "only" ], "type": "string", "description": "include (default) | exclude | only — sender == receiver rows (bill-pay funding, quick pays, self-sends)", "name": "self_payments", "in": "query" }, { "type": "string", "description": "RFC3339 lower bound (inclusive)", "name": "created_after", "in": "query" }, { "type": "string", "description": "RFC3339 upper bound (exclusive)", "name": "created_before", "in": "query" }, { "type": "string", "description": "exact on-chain hash (case-insensitive) — what a customer pastes into a ticket", "name": "tx_hash", "in": "query" }, { "type": "string", "description": "exact reference match", "name": "reference", "in": "query" }, { "type": "string", "description": "scope to a CYBRID customer guid, resolved to the account(s) holding it (other providers write their own id shapes into the same column and are not searched); a guid belonging to nobody returns an EMPTY page, never the tenant", "name": "customer_guid", "in": "query" }, { "enum": [ "only", "exclude" ], "type": "string", "description": "only | exclude — rows whose summed ROUTED settlements EXCEED notional_uoa. A memo is a payer-supplied bytes32 that can be routed more than once, and a route may declare a larger notional than the request asked for; either way the receiver holds more than the record says was owed. 24 such rows totalling $72.82 were invisible on megprime-prod before this filter.", "name": "overpaid", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AdminFulfillmentListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/fulfillments/timeseries": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Bucketed counts + notional sums for a single user, for the operator activity chart. `user_id` is matched on EITHER side (sender, receiver or creator) — the same party test GET /admin/fulfillments uses, so the chart and the list it drills into agree about whose transfer a row is. `bucket` is day|week|month. Sent/received split by the CHARTED user's role, not the caller's. `settled` counts only confirmed; `cancelled` folds cancelled|declined|expired and is returned as its OWN series rather than dropped — climbing cancellations are signal. `self_payments` defaults to **exclude**: a self→self fulfillment is funding plumbing, and counting it as customer activity misreads treasury operations as behaviour. Aggregated in SQL, so cost scales with buckets rather than transfers.", "produces": [ "application/json" ], "tags": [ "fulfillment" ], "summary": "One person's P2P activity over time (admin)", "operationId": "adminFulfillmentTimeseries", "parameters": [ { "type": "string", "description": "the person to chart (either side)", "name": "user_id", "in": "query", "required": true }, { "enum": [ "day", "week", "month" ], "type": "string", "description": "day|week|month (default day)", "name": "bucket", "in": "query" }, { "type": "string", "description": "RFC3339 lower bound (inclusive)", "name": "since", "in": "query" }, { "type": "string", "description": "RFC3339 upper bound (exclusive)", "name": "until", "in": "query" }, { "enum": [ "sent", "received", "all" ], "type": "string", "description": "sent|received|all (default all)", "name": "direction", "in": "query" }, { "enum": [ "include", "exclude", "only" ], "type": "string", "description": "include|exclude|only (default exclude)", "name": "self_payments", "in": "query" }, { "type": "string", "description": "view another tenant (admin only)", "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AdminFulfillmentTimeseriesResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/fulfillments/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Operator point lookup for a transfer named in a ticket. Fenced to the caller's tenant (or `tenant_id` for the admin role): an id in another tenant is a 404, never a 403, so the endpoint is not an existence oracle. Counterparty contact PII is scrubbed — the operator is not a party.", "produces": [ "application/json" ], "tags": [ "fulfillment" ], "summary": "One fulfillment by id (admin)", "operationId": "adminGetFulfillment", "parameters": [ { "type": "string", "description": "fulfillment id", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "view another tenant (admin only)", "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.FulfillmentResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/persons": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Platform-wide search over PERSONS (the cross-tenant human identity that accounts hang off), not accounts — requires the cross-tenant grant. This is how you find every account one human holds across tenants and spot a duplicate signup; an account-level search cannot see across tenant boundaries. tenant_id restricts to persons with a live account in that tenant; invited_by restricts to persons with an account invited by a given account id.", "produces": [ "application/json" ], "tags": [ "person" ], "summary": "Search persons", "operationId": "listPersons", "parameters": [ { "type": "string", "description": "email", "name": "email", "in": "query" }, { "type": "string", "description": "phone", "name": "phone", "in": "query" }, { "type": "string", "description": "free-text query", "name": "q", "in": "query" }, { "type": "boolean", "description": "verified_only", "name": "verified_only", "in": "query" }, { "type": "string", "description": "restrict to persons with a live account in this tenant", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "restrict to persons with an account invited by this account id", "name": "invited_by", "in": "query" }, { "type": "string", "description": "RFC3339 lower bound on created_at (inclusive)", "name": "created_after", "in": "query" }, { "type": "string", "description": "RFC3339 upper bound on created_at (exclusive)", "name": "created_before", "in": "query" }, { "enum": [ "name", "name_desc", "recent", "oldest" ], "type": "string", "description": "name (A-Z, default) | name_desc | recent | oldest", "name": "sort", "in": "query" }, { "type": "integer", "description": "limit", "name": "limit", "in": "query" }, { "type": "integer", "description": "offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/persons/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One person's platform-wide record: identity fields and every account they hold, across every tenant. Requires the cross-tenant grant, same as listPersons.", "produces": [ "application/json" ], "tags": [ "person" ], "summary": "Get person", "operationId": "getPerson", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonAdminDetailResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Cascading soft-delete of a cross-tenant PERSON, not a single account. A tenant_admin caller only removes that person's membership in the ADMIN'S OWN tenant — other tenants' accounts for the same person survive untouched; a system-admin (cross_tenant) caller deletes the person platform-wide. reason is optional and recorded for audit.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "person" ], "summary": "Delete person", "operationId": "deletePerson", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "reason", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ReasonRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonCascadeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Partial PII patch on a cross-tenant person: a field present in the JSON body is applied — even an empty string clears it — while an absent field is left unchanged, so a {} body is a no-op. username is rejected with 400 (it is account-scoped, not person-scoped; use PATCH /accounts/{id} instead). The regulated block — DOB, home address, primary email and phone — is echoed back in the response only to a system-admin (global) caller, never to a tenant_admin, so an empty patch cannot be used as a read of those fields at the lower gate.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "person" ], "summary": "Update person", "operationId": "updatePerson", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "profile fields", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.UpdatePersonRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/persons/{id}/merge-into/{target_id}": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "person" ], "summary": "Merge two persons", "operationId": "mergePerson", "parameters": [ { "type": "string", "description": "source id", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "target id", "name": "target_id", "in": "path", "required": true }, { "description": "reason", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ReasonRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonMergeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/persons/{id}/split/{account_id}": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "person" ], "summary": "Split account from person", "operationId": "splitPerson", "parameters": [ { "type": "string", "description": "source id", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "account id", "name": "account_id", "in": "path", "required": true }, { "description": "reason", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ReasonRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonSplitResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/referrals": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "referrals" ], "summary": "Get the referral leaderboard", "operationId": "adminListReferrals", "parameters": [ { "type": "string", "description": "tenant_id", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "referrer username / email (substring) or account id (exact)", "name": "q", "in": "query" }, { "enum": [ "referred_desc", "referred_asc", "kyc_verified_desc", "name_asc" ], "type": "string", "default": "referred_desc", "description": "ordering", "name": "sort", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ReferralLeaderboardResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/roles": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Every role in the catalog, built-in and custom — roles are a global table with no tenant_id, so this is not tenant-scoped. Gated on tenant_read or above; see also listRoles (GET /roles), the same underlying data exposed to ANY authenticated caller with no admin gate, for populating a role picker.", "produces": [ "application/json" ], "tags": [ "roles" ], "summary": "List", "operationId": "adminListRoles", "parameters": [ { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RolePageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Creates a custom role with an arbitrary permission grant. System-admin (platform-only) gated — there is no separate escalation fence because only a caller who already holds cross_tenant (the maximum grant) can reach this route at all. slug must match ^[a-z][a-z0-9_]{1,49}$ (mixed case is lowercased, not rejected) and may not collide with a built-in slug (admin, tenant_admin, developer, user), which returns 409.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "roles" ], "summary": "Create", "operationId": "createRole", "parameters": [ { "description": "role", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.CreateRoleRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RoleResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/roles/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One role by id, including its full permission grant (cross_tenant, tenant_read, tenant_write, tenant_manage, admin_managed).", "produces": [ "application/json" ], "tags": [ "roles" ], "summary": "Get", "operationId": "getRole", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RoleResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "put": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Updates a custom role's name, description, or permission grant (each field optional; permissions, if present, REPLACES the full set rather than merging individual flags). Built-in roles return 409 immutable. System-admin (platform-only) gated, for the same reason as createRole: only a cross_tenant holder can reach this route.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "roles" ], "summary": "Update", "operationId": "updateRole", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "role", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.UpdateRoleRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RoleResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Deletes a CUSTOM role only — built-in slugs (admin, tenant_admin, developer, user) return 409 conflict, as does a role still assigned to any account (reassign those accounts first). System-admin (platform-only) gated.", "produces": [ "application/json" ], "tags": [ "roles" ], "summary": "Delete", "operationId": "deleteRole", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/telemetry/bank-link": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The CS bank-link dashboard: client telemetry from the Plaid link + bank-exchange flows (source IN plaid_link, bank_link_exchange, external_bank_unlink). An explicit `source` query overrides the default set; `event` (e.g. EXIT) narrows further. Same tenant scoping and retention as the general feed.", "produces": [ "application/json" ], "tags": [ "telemetry" ], "summary": "Bank-link telemetry feed (admin)", "operationId": "adminBankLinkTelemetry", "parameters": [ { "type": "string", "description": "filter by tenant (admin only)", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "CSV override of the default bank-link sources", "name": "source", "in": "query" }, { "type": "string", "description": "single event filter, e.g. EXIT", "name": "event", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ClientEventListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/users/{account_id}/client-events": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "telemetry" ], "summary": "List For Account", "operationId": "adminListUserClientEvents", "parameters": [ { "type": "string", "description": "account_id", "name": "account_id", "in": "path", "required": true }, { "type": "string", "description": "tenant_id assertion", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "CSV of sources to include (e.g. plaid_link,bank_link_exchange,plaid_refresh_patch,external_bank_unlink,bank_link_funnel) — same semantics as the tenant feed", "name": "source", "in": "query" }, { "type": "string", "description": "exact event name (e.g. EXIT)", "name": "event", "in": "query" }, { "type": "string", "description": "narrow to one session (enforcer or Privy session id)", "name": "session_id", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ClientEventListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/users/{account_id}/contacts": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Lets support/tenant_admin/admin browse ANOTHER account's contacts (account_id path param), same filters and sort as GET /contacts. Tenant-scoped callers (tenant_admin, developer — any tenant_read grant) may only browse accounts in their own tenant; a foreign-tenant account id returns 404, never 403, so the route can't be used to probe which account ids exist elsewhere.", "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Admin Browse", "operationId": "adminListUserContacts", "parameters": [ { "type": "string", "description": "account_id", "name": "account_id", "in": "path", "required": true }, { "type": "string", "description": "search query", "name": "q", "in": "query" }, { "type": "string", "description": "contact_type", "name": "contact_type", "in": "query" }, { "type": "boolean", "description": "active", "name": "active", "in": "query" }, { "type": "boolean", "description": "blacklisted", "name": "blacklisted", "in": "query" }, { "type": "boolean", "description": "when true, only favorited contacts (favorite_rank set)", "name": "favorite", "in": "query" }, { "enum": [ "name", "display_name", "name_desc", "display_name_desc", "recent", "oldest" ], "type": "string", "description": "name / display_name (A-Z, default) | name_desc / display_name_desc | recent | oldest", "name": "sort", "in": "query" }, { "type": "integer", "description": "limit", "name": "limit", "in": "query" }, { "type": "integer", "description": "offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ContactPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/users/{account_id}/identity": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Live identity-provider state for one account beside enforcer's own row: the account's stored email/phone and their verified flags, the VERIFIED contacts Privy holds right now, whether they still agree, and the live passkey MFA posture. email_matches_account is the field to read first — a Privy-linked address that has drifted from accounts.email sends every login code to an inbox the user no longer reads, and nothing else in the database exposes that. Both match fields are null (never false) when either side is blank, since \"Privy holds no email\" is a different problem from \"the emails disagree\"; both values ship in the body so a null always explains itself. privy is null for an account with no Privy user (native/SSO tenants), which is a fact about the tenant, not a fault. A Privy read that fails refuses the whole response rather than serving it with the provider half silently missing.", "produces": [ "application/json" ], "tags": [ "admin" ], "summary": "Privy identity state for an account", "operationId": "adminGetUserIdentity", "parameters": [ { "type": "string", "description": "account id", "name": "account_id", "in": "path", "required": true }, { "type": "string", "description": "tenant_id assertion — 404s when it does not match the account's tenant", "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AdminIdentityResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/users/{account_id}/verifications": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Admin-read of ONE account's verification sessions (one row per provider and type), carrying the same server-computed `can_retry`, `blocked_reason` and `remedy` the account owner sees. `can_retry` is the gate a client should branch on — never re-derive it from `status`, which gets `expired` and `failed` wrong (both are retryable; only a customer-level rejection is terminal) and reports a verified account as blocked. `blocked_reason` is `customer_rejected` (only the provider's compliance team can lift it), `already_verified` (a SUCCESS, not a block), or absent. Tenant-scoped: naming an account in another tenant is 403 `account_not_in_tenant`, not 404, so the id space cannot be probed — a system admin with cross_tenant reads any tenant.", "produces": [ "application/json" ], "tags": [ "verification" ], "summary": "List an account's verification sessions (admin)", "operationId": "adminListVerificationSessions", "parameters": [ { "type": "string", "description": "account id (uuid)", "name": "account_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SessionsResponse" } }, "400": { "description": "invalid_account_id", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "account_not_in_tenant", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "account_not_found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/wallet-audit": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The custody drift worklist: accounts whose LIVE signing posture does not match what our rows claim. Open findings only unless include_resolved=true. Ordered worst-and-oldest first (critical before warning, then by how long the condition has persisted).", "produces": [ "application/json" ], "tags": [ "wallet-audit" ], "summary": "List wallet custody drift findings", "operationId": "listWalletAuditFindings", "parameters": [ { "type": "string", "description": "filter by tenant", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "filter by account", "name": "account_id", "in": "query" }, { "enum": [ "wallet.app_only_custody", "wallet.cosign_not_enforced", "wallet.quorum_unreadable", "wallet.owner_drift", "wallet.unmigrated_primary", "tenant.illegal_web3_gates" ], "type": "string", "description": "filter by rule", "name": "rule", "in": "query" }, { "enum": [ "critical", "warning", "info" ], "type": "string", "description": "filter by severity", "name": "severity", "in": "query" }, { "type": "boolean", "description": "include resolved history", "name": "include_resolved", "in": "query" }, { "type": "integer", "description": "page size (default 50, max 200)", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.WalletAuditListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/admin/wallets/accounts/{id}/adopt-multisig": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Threads an ALREADY-EXISTING quorum-owned Privy wallet into account_wallets as the account's multisig wallet, and makes it primary. For wallets minted outside v3 (a migration spike, or by hand during an incident) — those are invisible on the Privy user object, so no automatic path can discover them, and the ensure path would mint a duplicate instead of adopting. The wallet's live owner quorum is VERIFIED to be a true 2-of-2 naming this account's Privy user before anything is written; a mistyped wallet id is refused rather than recorded. Refuses when the account already records a multisig wallet.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "directory" ], "summary": "Adopt an existing Privy wallet as the account's 2-of-2 wallet", "operationId": "adoptAccountMultisigWallet", "parameters": [ { "type": "string", "description": "account id", "name": "id", "in": "path", "required": true }, { "description": "the Privy wallet to adopt", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AdoptMultisigWalletRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AdoptMultisigWalletResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "422": { "description": "Unprocessable Entity", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/api-keys": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Machine credentials visible to the caller: their own keys, or — for a tenant admin — every key issued in their tenant. The plaintext secret is never returned here or anywhere after creation; only id, name, key_prefix, active and last_used_at are exposed.", "produces": [ "application/json" ], "tags": [ "api-keys" ], "summary": "List", "operationId": "listApiKeys", "parameters": [ { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ApiKeyPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Mints a new API key for the CALLER's own account and returns the plaintext exactly once in this response — it is never retrievable again. name is required and cannot be blank: an unnamed key is a working credential nobody can identify to revoke later, so an empty or whitespace-only name is rejected with 400 missing_fields rather than silently minting an anonymous key. The minted key inherits the CALLER's full role and permissions — it is not a narrower credential.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "api-keys" ], "summary": "Create", "operationId": "createApiKey", "parameters": [ { "description": "api key", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.CreateKeyRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ApiKeyCreatedResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/api-keys/{id}": { "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Hard-removes an API key row (ResourceAuth write — the key's own account, or a tenant admin over their tenant's keys). Unlike Revoke, this does not leave an inactive row for audit; prefer POST /api-keys/{id}/revoke when the goal is to disable the credential while keeping a record it existed. 404 key_not_found for an unknown or out-of-scope id.", "produces": [ "application/json" ], "tags": [ "api-keys" ], "summary": "Delete", "operationId": "deleteApiKey", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/api-keys/{id}/revoke": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "api-keys" ], "summary": "Revoke API key", "operationId": "revokeApiKey", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/audit-events": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The audit trail, newest first, filter-scoped by role: admin sees every tenant, tenant_admin sees only their own tenant, everyone else sees nothing (not even their own actions — use GET /me/audit-events instead). from/to accept RFC3339 or YYYY-MM-DD; a malformed bound is a 400, not a silently ignored filter. session_id matches EITHER the enforcer refresh-token family (session_id) or the upstream provider's session (external_session_id, e.g. a Privy sid), so one query finds every audit event from one login regardless of which id space logged it.", "produces": [ "application/json" ], "tags": [ "audit" ], "summary": "List", "operationId": "listAuditEvents", "parameters": [ { "type": "string", "description": "filter by actor account id", "name": "actor_account_id", "in": "query" }, { "type": "string", "description": "filter by action (e.g. person.updated)", "name": "action", "in": "query" }, { "type": "string", "description": "filter by resource type (e.g. person)", "name": "resource_type", "in": "query" }, { "type": "string", "description": "filter by resource id", "name": "resource_id", "in": "query" }, { "type": "string", "description": "created_at \u003e= (RFC3339 or YYYY-MM-DD); malformed = 400", "name": "from", "in": "query" }, { "type": "string", "description": "created_at \u003c= (RFC3339 or YYYY-MM-DD); malformed = 400", "name": "to", "in": "query" }, { "enum": [ "recent", "oldest" ], "type": "string", "default": "recent", "description": "sort order", "name": "sort", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" }, { "type": "string", "description": "one login's events — matches session_id (enforcer refresh-token family) OR external_session_id (the provider's, e.g. a Privy sid)", "name": "session_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuditEventPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/audit-events/summary": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Counts over the SAME compiled row filter and from/to window semantics as GET /audit-events (including the RFC3339-or-YYYY-MM-DD parsing and malformed-bound-is-400 rule), so a summary tile never claims a count the event list itself would refuse to show. group_by is one of action, resource_type or actor (actor buckets NULL actor_account_id — system-initiated events like verification grants — under the explicit key \"system\" rather than leaving it blank); interval adds a time-bucketed data.series over the same window.", "produces": [ "application/json" ], "tags": [ "audit" ], "summary": "Summary", "operationId": "summarizeAuditEvents", "parameters": [ { "type": "string", "description": "action | resource_type | actor", "name": "group_by", "in": "query" }, { "type": "string", "description": "filter by action", "name": "action", "in": "query" }, { "type": "string", "description": "filter by resource type", "name": "resource_type", "in": "query" }, { "type": "string", "description": "filter by actor account id", "name": "actor_account_id", "in": "query" }, { "type": "string", "description": "RFC3339 lower bound (inclusive)", "name": "since", "in": "query" }, { "type": "string", "description": "RFC3339 upper bound (exclusive)", "name": "until", "in": "query" }, { "type": "string", "description": "hour | day | week | month — returns data.series", "name": "interval", "in": "query" }, { "type": "string", "description": "one login's events — matches session_id OR external_session_id", "name": "session_id", "in": "query" }, { "type": "string", "description": "IANA time zone for bucketing (default UTC)", "name": "tz", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Response" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/config": { "get": { "description": "Public: given an optional `tenant_code`, reports how that tenant's login UI should authenticate — native OTP/passkey/SIWE vs. Privy custom auth — plus the tenant's public `privy_app_id` (never a secret) so the client can initialize the right SDK before the user picks a method.", "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Auth Config Bootstrap", "operationId": "getAuthConfig", "parameters": [ { "type": "string", "description": "tenant routing code", "name": "tenant_code", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthConfigResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/device-providers": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The push providers configured on this deployment (e.g. FCM/APNs), for a client choosing which provider code to pass to registerDevice.", "produces": [ "application/json" ], "tags": [ "devices" ], "summary": "List Providers", "operationId": "listDeviceProviders", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DeviceProviderListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/email-status": { "get": { "description": "Public, rate-limited: given `email` (and optional `tenant_code`), reports whether an account with that address already exists and is verified WITHIN THAT ONE TENANT, so a signup UI can route to login vs. register vs. \"email taken\" without leaking whether the address is registered in any other tenant. `email` must parse as a bare address (no display-name form, no dotless domain) or the call is a 400 `invalid_email`, distinct from the 200 `exists:false` a well-formed-but-unregistered address returns.", "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Email Status", "operationId": "getEmailStatus", "parameters": [ { "type": "string", "description": "email to check", "name": "email", "in": "query", "required": true }, { "type": "string", "description": "tenant routing code", "name": "tenant_code", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.EmailStatusResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/invites/accept": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The authenticated caller redeems an invite token and gains the membership it grants. 410 invite_invalid if the token is expired, already used, or cancelled; 403 email_mismatch if the invite was addressed to a different email than the caller's verified identity.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "invites" ], "summary": "Accept", "operationId": "acceptInvite", "parameters": [ { "description": "invite token", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AcceptInviteRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AccountResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "410": { "description": "Gone", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/login": { "post": { "description": "Authenticates a credential and, on success, issues an enforcer access/refresh token pair (200, `handler.AuthResponse`). `provider` in the request selects the scheme and its required fields: `email_otp` needs `email`+`code`, `phone_otp` needs `phone`+`code`, `siwe` needs `message`+`signature`, every other provider needs `token` (e.g. a Privy access token). 401 on a rejected credential or wrong/expired OTP, 403 `account_inactive` for a deactivated account or `wrong_auth_scheme` when the tenant requires a different provider, 404 when no tenant matches the credential, 409 only on a benign concurrent-refresh race elsewhere in the family, 503 when the upstream identity provider (Privy/Google) is unreachable.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Login", "operationId": "login", "parameters": [ { "description": "credential + optional tenant routing", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_auth.LoginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/logout": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Revokes the caller's entire refresh-token family (all devices/sessions sharing that `refresh_token`'s lineage), given `refresh_token` in the body. 401 if the token doesn't resolve to the caller.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Logout", "operationId": "logout", "parameters": [ { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.LogoutRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/me": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The authenticated caller's own identity in one call: account (id, tenant, role, wallet address, login/activity timestamps), permissions, verification sessions plus the derived KYC-verified flag, resolved authz groups (id/slug/name), inline terms-acceptance posture, the caller's referral code, and — for a send-enforced tenant with a smart wallet not yet migrated — a `wallet_send_migration_required` flag. Terms and referral data are best-effort: a lookup hiccup on either omits that field rather than failing the whole call.", "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Current identity", "operationId": "getMe", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.MeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/me/devices": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "devices" ], "summary": "List my devices", "operationId": "listDevices", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DeviceListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Register or refresh a push-capable device under the caller's person: provider + push_token are required, plus device_id/device_name, os_name/os_version, app_identifier/app_version, and — for signed push — public_key/key_algorithm, with free-form metadata. An unknown provider code is 400 unknown_provider.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "devices" ], "summary": "Register", "operationId": "registerDevice", "parameters": [ { "description": "device", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RegisterDeviceRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DeviceResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/me/devices/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One of the caller's own registered devices — push token, OS, app version, and any registered public key. Scoped to the caller's person; an id belonging to someone else's device is 404, not 403.", "produces": [ "application/json" ], "tags": [ "devices" ], "summary": "Get", "operationId": "getDevice", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DeviceResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Unregister a device from the caller's own person-scoped registry (push token + key material for that install). Scoped to the caller's person, so an id belonging to someone else's device returns 404 device_not_found, never 403.", "produces": [ "application/json" ], "tags": [ "devices" ], "summary": "Unregister", "operationId": "deleteDevice", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Rename a device (device_name) or change its status independently; either field may be omitted.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "devices" ], "summary": "Update", "operationId": "updateDevice", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "device fields", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.UpdateDeviceRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DeviceResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/me/passkey/verify": { "post": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Verify passkey MFA enrollment", "operationId": "verifyPasskeyMfa", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PasskeyMfaVerifyResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/me/phone/capture": { "post": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Capture phone at SMS-MFA enrollment", "operationId": "captureMfaPhone", "parameters": [ { "description": "phone in any common format; stored canonicalized (+digits)", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PhoneCaptureRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PhoneCaptureResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/me/terms": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The onboarding gate: the caller's current terms per type (a tenant-specific version overrides the global one for the same type), each flagged accepted/accepted_at, plus has_mandatory_pending — true if any MANDATORY document among them is still unaccepted. Poll this after acceptMyTerms to confirm the gate cleared.", "produces": [ "application/json" ], "tags": [ "terms" ], "summary": "My Status", "operationId": "getMyTerms", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TermsStatusResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/me/terms/{id}": { "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Withdraws the caller's own consent to a document by id (idempotent — revoking an unaccepted or already-revoked id is a no-op). The acceptance row is deleted, but the revocation itself is retained in the audit log for compliance. Revoking a MANDATORY document's acceptance will re-trip has_mandatory_pending on the next getMyTerms call.", "produces": [ "application/json" ], "tags": [ "terms" ], "summary": "Revoke terms acceptance", "operationId": "revokeMyTerms", "parameters": [ { "type": "string", "description": "terms id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/me/terms/{id}/accept": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Records the caller's consent to one document by id, snapshotting its content hash, version, IP and user-agent at accept time — so a later edit to the document's content never retroactively changes what the caller is considered to have agreed to. Idempotent: re-accepting an already-accepted id is a no-op, not a duplicate row or an error.", "produces": [ "application/json" ], "tags": [ "terms" ], "summary": "Accept terms", "operationId": "acceptMyTerms", "parameters": [ { "type": "string", "description": "terms id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/otp/request": { "post": { "description": "Public: starts the native `email_otp` login/registration flow by emailing a one-time code to `email` (optionally scoped by `tenant_code`). Always 200 `{message:\"code sent\"}` on success; the code itself is only echoed in the response body when the deployment has `expose_dev_otp` enabled (local/dev only).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Request O T P", "operationId": "requestOtp", "parameters": [ { "description": "otp target", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_auth.RequestOTPInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OtpRequestResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/passkey/credentials": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The caller's own registered WebAuthn/passkey credentials — never another account's.", "produces": [ "application/json" ], "tags": [ "passkey" ], "summary": "List", "operationId": "listPasskeyCredentials", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.CredentialListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/passkey/credentials/{id}": { "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "passkey" ], "summary": "Delete passkey credential", "operationId": "deletePasskeyCredential", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/passkey/login/begin": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Passkey Login Begin", "operationId": "beginPasskeyLogin", "parameters": [ { "description": "optional tenant code", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PasskeyLoginBeginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PasskeyChallengeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/passkey/login/finish": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Passkey Login Finish", "operationId": "finishPasskeyLogin", "parameters": [ { "description": "webauthn assertion", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PasskeyLoginFinishRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/passkey/register/begin": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Starts the WebAuthn registration ceremony for the authenticated account: returns creation options plus an opaque handle that MUST be echoed back unchanged to finishPasskeyRegistration — it is how the server matches the attestation to this specific challenge. 409 webauthn_not_configured if the tenant has no relying party set up; 503 passkeys_disabled if ceremonies are turned off tenant-wide.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "passkey" ], "summary": "Register Begin", "operationId": "beginPasskeyRegistration", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PasskeyChallengeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/passkey/register/finish": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Completes the ceremony started by beginPasskeyRegistration: verifies the attestation response against the handle issued there and stores the credential under friendly_name. A stale, reused, or mismatched handle fails with the same 400 passkey_failed as a malformed attestation — the ceremony does not distinguish client bugs from a forged response in its error body.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "passkey" ], "summary": "Register Finish", "operationId": "finishPasskeyRegistration", "parameters": [ { "description": "webauthn credential", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RegisterFinishReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.CredentialResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/privy/register": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Privy Custom Auth Register", "operationId": "registerPrivy", "parameters": [ { "description": "email + optional tenant routing", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_auth.RegisterPrivyInput" } } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PrivyRegisterResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/refresh": { "post": { "description": "Exchanges a `refresh_token` for a new access/refresh token pair. 401 `invalid_refresh_token` if the token is unknown or was already reused (reuse of a rotated-out token revokes the whole family — a theft signal), 409 `refresh_raced` when a concurrent refresh in the same family already rotated it (benign — retry with the client's latest stored token, do not treat as a logout).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Refresh", "operationId": "refreshToken", "parameters": [ { "description": "refresh token", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RefreshRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/register": { "post": { "description": "Creates an account/person via the same per-provider verification `login` uses (see `login`'s description for the `provider` field rules), but returns the created account (`handler.RegisterResponse`) rather than issuing tokens — the caller must still call `login` (or, for `privy_custom_auth` tenants, complete the Privy flow) to sign in. 200 if the account already existed for this credential (idempotent), 201 if newly created, 409 `email_taken` if the email is already registered in this tenant under a different provider.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Register", "operationId": "register", "parameters": [ { "description": "credentials", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_auth.LoginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RegisterResponse" } }, "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RegisterResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/sessions": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The caller's own active and recent login sessions (device, IP, issued/last-seen times). Scoped to the caller only — there is no cross-account session listing here.", "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Sessions", "operationId": "listSessions", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SessionListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/sessions/{id}": { "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Revoke one of the caller's own login sessions by its session/family id. A session not owned by the caller returns 404, never a cross-account 403 — this is not an existence oracle for other users' sessions.", "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Revoke Session", "operationId": "revokeSession", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/siwe/nonce": { "post": { "description": "Public: issues a single-use nonce for `wallet_address` (optionally scoped by `tenant_code`) that the client embeds in its EIP-4361 \"Sign-In with Ethereum\" message; `login` with `provider: siwe` then verifies `message`+`signature` against it.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Request S I W E Nonce", "operationId": "getSiweNonce", "parameters": [ { "description": "wallet address", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SiweNonceRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SiweNonceResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/sms/request": { "post": { "description": "Public: starts a Twilio Verify SMS login challenge to `phone`, scoped by `tenant_code`. 400 if SMS verification isn't configured for the tenant (no Verify client wired or no active Twilio connection) or if rate-limited.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Request SMS login code", "operationId": "requestSms", "parameters": [ { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RequestSMSRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.MessageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/sso/exchange": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Exchange SSO code for tokens", "operationId": "ssoExchange", "parameters": [ { "description": "single-use code from the callback redirect", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SSOExchangeRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/sso/{connection}/acs": { "post": { "consumes": [ "application/x-www-form-urlencoded" ], "tags": [ "auth" ], "summary": "SAML SSO assertion consumer service", "operationId": "ssoACS", "parameters": [ { "type": "string", "description": "sso connection id or slug", "name": "connection", "in": "path", "required": true }, { "type": "string", "description": "base64 SAML response", "name": "SAMLResponse", "in": "formData", "required": true }, { "type": "string", "description": "relay state from the authn request", "name": "RelayState", "in": "formData", "required": true } ], "responses": { "302": { "description": "redirect to the tenant app with ?sso_code (or ?sso_error)", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/sso/{connection}/callback": { "get": { "tags": [ "auth" ], "summary": "OIDC SSO callback", "operationId": "ssoCallback", "parameters": [ { "type": "string", "description": "sso connection id or slug", "name": "connection", "in": "path", "required": true }, { "type": "string", "description": "authorization code", "name": "code", "in": "query" }, { "type": "string", "description": "state", "name": "state", "in": "query" } ], "responses": { "302": { "description": "redirect to the tenant app with ?sso_code (or ?sso_error)", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/sso/{connection}/metadata": { "get": { "produces": [ "text/xml" ], "tags": [ "auth" ], "summary": "SAML SP metadata", "operationId": "ssoMetadata", "parameters": [ { "type": "string", "description": "sso connection id or slug", "name": "connection", "in": "path", "required": true } ], "responses": { "200": { "description": "SAML SP EntityDescriptor XML", "schema": { "type": "string" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/sso/{connection}/start": { "get": { "tags": [ "auth" ], "summary": "Start SSO login", "operationId": "ssoStart", "parameters": [ { "type": "string", "description": "sso connection id or slug", "name": "connection", "in": "path", "required": true } ], "responses": { "302": { "description": "redirect to the tenant's identity provider", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/tenant/join": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Creates a membership for the caller's existing person in the tenant identified by `tenant_code` (an open/joinable tenant's invite code), reusing the same person rather than creating a new one — idempotent if the caller already has an account there. Returns a fresh token pair scoped to that tenant. 201 if the membership was newly created, 200 if it already existed, 403 join-not-allowed and inactive-tenant cases, 404 if the code matches no tenant.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Join Tenant", "operationId": "joinTenant", "parameters": [ { "description": "invite/join code", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.JoinTenantRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthResponse" } }, "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/tenant/switch": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Issues a new token pair scoped to the caller's account in a DIFFERENT tenant they already belong to, given that tenant's `tenant_id`. 403 `no_membership` if the caller's person has no account in the target tenant — this does not create one (see `joinTenant` for that).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Switch Tenant", "operationId": "switchTenant", "parameters": [ { "description": "target tenant", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SwitchTenantRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/tenants": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Every tenant membership (account row) belonging to the caller's PERSON, across all tenants that person has an account in — the multi-tenant membership list `/auth/tenant/switch` picks from.", "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Memberships", "operationId": "listMyTenants", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AccountListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/turnstile/verify": { "post": { "description": "Public: confirms a Cloudflare Turnstile widget response token server-side (forwarding the caller's IP as `remoteip`) and reports pass/fail. A failed challenge is returned as 200 `{success:false, ...error codes}`, not a 4xx, so the client can distinguish \"try the widget again\" from a malformed request; 503 if no Turnstile secret is configured on this deployment (fails loud rather than silently passing every caller).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Verify Turnstile", "operationId": "verifyTurnstile", "parameters": [ { "description": "turnstile token", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TurnstileVerifyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TurnstileVerifyResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/verify/email/check": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Check email verification code", "operationId": "checkEmailVerification", "parameters": [ { "description": "email + code", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.EmailCheckRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.MessageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "422": { "description": "Unprocessable Entity", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/verify/email/start": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Start email verification", "operationId": "startEmailVerification", "parameters": [ { "description": "email", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.EmailStartRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.MessageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "422": { "description": "Unprocessable Entity", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/verify/phone/check": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Check phone verification code", "operationId": "checkPhoneVerification", "parameters": [ { "description": "phone + code", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PhoneCheckRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.MessageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "422": { "description": "Unprocessable Entity", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/auth/verify/phone/start": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Start phone verification", "operationId": "startPhoneVerification", "parameters": [ { "description": "phone", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PhoneStartRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.MessageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "422": { "description": "Unprocessable Entity", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/authz/check": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Evaluates an authorization decision for the caller (or, with `user_id`, for another account the caller may read).\n\n**The `resource` is a description, not a lookup.** Nothing loads the row behind `resource.id`, so the request must carry whatever the rules match on — `owner_id` for the owner baseline, `tenant_id` for any tenant-scoped grant (including every admin-managed type: tenant, connection, email_template, terms, group_type, …). A request naming only `{type, id}` is judged against an empty tenant and an empty owner: it returns `allow:false` with `reason:\"resource_unspecified\"`, which means the request under-described the resource — not that a tenancy check failed.\n\nExample of a same-tenant read that can actually be allowed:\n`{\"action\":\"read\",\"resource\":{\"type\":\"account\",\"id\":\"\u003cid\u003e\",\"tenant_id\":\"\u003ccaller tenant\u003e\",\"owner_id\":\"\u003cid\u003e\"}}`", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "authz" ], "summary": "Authorization check", "operationId": "authzCheck", "parameters": [ { "description": "check request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_policies.EvaluateInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthzCheckResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/connections": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Filter-scoped by role: admin sees every tenant's connections, tenant_admin sees their own tenant's, user/developer see none. List rows never carry config — only Get/Create/Update return a (redacted) config, and even those never return raw credentials.", "produces": [ "application/json" ], "tags": [ "connections" ], "summary": "List", "operationId": "listConnections", "parameters": [ { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ConnectionPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Creates a connection in the CALLER's tenant (tenant_admin/admin only). config is sealed with AES-256-GCM before it touches the database and is never returned in plaintext by this or any other route — Create's response has the same redaction as Get. provider_id must resolve to a known provider or the call fails.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "connections" ], "summary": "Create connection", "operationId": "createConnection", "parameters": [ { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_connections.CreateInput" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ConnectionResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/connections/capabilities": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The global catalog of connection capability types (e.g. webhook receiver, third-party integration). Not tenant-scoped — every authenticated caller sees the same fixed list, independent of what their tenant has configured.", "produces": [ "application/json" ], "tags": [ "connections" ], "summary": "List Capabilities", "operationId": "listConnectionCapabilities", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.CapabilityListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/connections/providers": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "connections" ], "summary": "List connection providers", "operationId": "listConnectionProviders", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ProviderListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/connections/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One connection with config REDACTED: only keys on an explicit per-provider public-key allowlist are returned in the clear (e.g. non-secret settings); every other key comes back as a fixed redacted-value marker, never the real credential. ResourceAuth-gated (tenant_admin/admin only) — the fenced value round-trips through PATCH without ever exposing the real secret.", "produces": [ "application/json" ], "tags": [ "connections" ], "summary": "Get", "operationId": "getConnection", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ConnectionResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Removes the connection row (and its sealed credentials) permanently. Irreversible; a tenant relying on it (e.g. its only cdp/alchemy/quicknode webhook receiver, or a trello/rain integration) loses that capability immediately.", "produces": [ "application/json" ], "tags": [ "connections" ], "summary": "Delete", "operationId": "deleteConnection", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Partial update (ResourceAuth write: tenant_admin/admin only). A config field sent as the redacted marker value (i.e. round-tripping what Get returned) leaves that key's stored secret untouched rather than overwriting it with the literal marker — only fields with a REAL new value replace the sealed credential.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "connections" ], "summary": "Update connection", "operationId": "updateConnection", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_connections.UpdateInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ConnectionResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/contacts": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The caller's own address book. contact_type is linked (points at a real platform account) or custom (off-platform, owner-entered details). favorite=true returns only favorited contacts; favorites always sort first regardless of the sort param. Rows are overlaid (best-effort) with each linked contact's unacked-fulfillment badge from enforcer-cybrid — a badge omission means the overlay call failed or is disabled, not that the count is zero.", "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Search", "operationId": "listContacts", "parameters": [ { "type": "string", "description": "search query", "name": "q", "in": "query" }, { "type": "string", "description": "contact_type", "name": "contact_type", "in": "query" }, { "type": "boolean", "description": "active", "name": "active", "in": "query" }, { "type": "boolean", "description": "blacklisted", "name": "blacklisted", "in": "query" }, { "type": "boolean", "description": "when true, only favorited contacts (favorite_rank set)", "name": "favorite", "in": "query" }, { "type": "string", "description": "name / display_name (A-Z, default) | name_desc / display_name_desc | recent | oldest. Favorites always sort first.", "name": "sort", "in": "query" }, { "type": "integer", "description": "limit", "name": "limit", "in": "query" }, { "type": "integer", "description": "offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ContactPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Creates either a LINKED contact (pass contact_account_id — must be a discoverable account per the same rules as suggestions/lookup, or 403/404) or a CUSTOM one (omit it; requires at least one of name/email/phone/wallet — 400 bad_request otherwise). Duplicate detection is per-field: a repeat contact_account_id, custom_email, or custom_wallet_address returns 409 rather than a second row — scanning the same payment QR twice is expected to resolve to the existing contact. custom_wallet_address must be a validly-shaped address (400 invalid_wallet_address otherwise) and becomes the contact's pay-to destination.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Create", "operationId": "createContact", "parameters": [ { "description": "contact", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.CreateContactRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ContactResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/contacts/bulk": { "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Deletes multiple of the CALLER's OWN contacts by id in one call (ids in the body). Ids that don't belong to the caller are silently skipped, not errored — the response count is how many rows actually deleted.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Delete Bulk", "operationId": "bulkDeleteContacts", "parameters": [ { "description": "contact ids to delete", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.IDsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DeletedResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/contacts/import": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Bulk-creates LINKED contacts from a list of account ids (ids in the body). Never fails as a batch: the response reports imported, skipped (already a contact — not an error), and failed (with a per-id reason in errors), so a caller can retry only the failures.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Import", "operationId": "importContacts", "parameters": [ { "description": "account ids to import as contacts", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.IDsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ContactImportResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/contacts/lookup": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Lookup users to add as contacts", "operationId": "lookupContactUsers", "parameters": [ { "type": "string", "description": "free-text search", "name": "q", "in": "query" }, { "type": "string", "description": "filter by first name (partial)", "name": "first_name", "in": "query" }, { "type": "string", "description": "filter by last name (partial)", "name": "last_name", "in": "query" }, { "type": "string", "description": "filter by username (partial)", "name": "username", "in": "query" }, { "type": "string", "description": "filter by email (partial)", "name": "email", "in": "query" }, { "type": "string", "description": "filter by phone (partial)", "name": "phone", "in": "query" }, { "type": "string", "description": "filter by wallet address (exact)", "name": "wallet_address", "in": "query" }, { "type": "string", "description": "filter by account id (exact)", "name": "user_id", "in": "query" }, { "type": "string", "description": "name (A-Z, default) | name_desc | recent", "name": "sort", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DiscoveryPageResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/contacts/resolve": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Resolve user by wallet address", "operationId": "resolveContactByAddress", "parameters": [ { "type": "string", "description": "wallet address", "name": "address", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DiscoveryResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/contacts/send-destinations": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The caller's KNOWN on-chain destinations, derived from their own address\nbook: linked contacts resolve to that member's ACTIVE wallet, custom\ncontacts to the wallet address the caller registered on them.\nBlacklisted and inactive contacts are excluded.\nNOT an exclusive allow-list — a user may also send to an arbitrary\nexternal address, governed by the per-transaction cap and the rolling\nweb3 allowance. These are the destinations that can be referenced by\ncontact id and shown by name.", "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "List known send destinations", "operationId": "listSendDestinations", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SendDestinationsResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/contacts/suggestions": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Discoverable tenant accounts the caller hasn't added yet — the \"people you may want to add\" feed. Requires: same tenant, is_discoverable=true, active=true, a VERIFIED kyc or kyb session, and excludes the caller and anyone already linked as a contact. Returns an empty page (not an error) when the tenant has discovery turned off tenant-wide.", "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Suggest contacts", "operationId": "suggestContacts", "parameters": [ { "type": "string", "description": "free-text search (username/email/first/last/wallet/phone)", "name": "q", "in": "query" }, { "type": "string", "description": "filter by first name (partial)", "name": "first_name", "in": "query" }, { "type": "string", "description": "filter by last name (partial)", "name": "last_name", "in": "query" }, { "type": "string", "description": "filter by username (partial)", "name": "username", "in": "query" }, { "type": "string", "description": "filter by email (partial)", "name": "email", "in": "query" }, { "type": "string", "description": "filter by phone (partial)", "name": "phone", "in": "query" }, { "type": "string", "description": "filter by wallet address (exact)", "name": "wallet_address", "in": "query" }, { "type": "string", "format": "uuid", "description": "filter by account id (exact)", "name": "user_id", "in": "query" }, { "type": "string", "description": "comma list: email,phone", "name": "require_verified", "in": "query" }, { "type": "string", "description": "comma list of account ids to also suppress", "name": "exclude_account_ids", "in": "query" }, { "enum": [ "name", "name_desc", "recent", "oldest", "active" ], "type": "string", "default": "name", "description": "sort order", "name": "sort", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DiscoveryPageResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/contacts/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One of the caller's own contacts, with the same unacked-fulfillment badge overlay as GET /contacts. Owner-enforced like the rest of the self-service contact routes.", "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Get", "operationId": "getContact", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ContactResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "put": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Partial update of the caller's own contact. custom_wallet_address may only be set/cleared on a CUSTOM contact — 400 on a linked one, whose payable address is always that account's own active wallet. For both custom_wallet_address and custom_avatar_url, send \"\" to explicitly clear the field; omit it to leave the stored value unchanged.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Update", "operationId": "updateContact", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "contact fields to update", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.UpdateContactRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ContactResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Deletes one of the caller's own contacts. Owner-enforced: an id belonging to someone else's address book 404s the same as an unknown id.", "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Delete", "operationId": "deleteContact", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/contacts/{id}/favorite": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "An owner may keep MANY favorites. Any non-null rank FAVORITES the contact (appended to the end of the favorites list — it never unfavorites another contact; already-favorited is a no-op); rank=null UNFAVORITES it. favorite_rank is a per-owner ordering, not a single slot, and favorites float to the top of the contacts list.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Favorite / unfavorite a contact", "operationId": "setContactFavorite", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "rank (null to unfavorite)", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SetContactFavoriteRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ContactResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/contacts/{id}/link": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Promotes an existing CUSTOM contact to LINKED by pointing it at a real account id (target_account_id) — the \"I scanned/typed this address and it turns out to be a platform user\" path. Clears the custom_* placeholder fields (email/phone/first/last name) since a linked row's identity now comes from the real account. 400 bad_request if the contact is already linked; the target must pass the same discoverability checks as Create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "contacts" ], "summary": "Link", "operationId": "linkContact", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "account to link to", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.LinkContactRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ContactResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/directory/accounts/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Service-to-service identity lookup: one account projected to {email, name, role, tenant, active, kyc_verified} — the read-only directory API v3 exposes so leaf services (enforcer-kv, enforcer-files, etc.) stop calling the legacy enforcer /admin/* shape. Gated to admin/service callers, not end users.", "produces": [ "application/json" ], "tags": [ "directory" ], "summary": "Get Account", "operationId": "getDirectoryAccount", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DirectoryRecordResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/directory/accounts/{id}/groups": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Group ids an account belongs to, for a leaf service's own authorization decisions (e.g. gating a feature on tenant group membership) without that service maintaining its own copy of v3's group table.", "produces": [ "application/json" ], "tags": [ "directory" ], "summary": "Account Groups", "operationId": "getDirectoryAccountGroups", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.StringListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/directory/accounts:batch": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Resolve many account ids to directory records in one round trip — the same {email, name, role, tenant, active, kyc_verified} projection as getDirectoryAccount. An id in account_ids that fails to parse as a UUID is silently skipped rather than failing the whole batch, so the response can be shorter than the request.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "directory" ], "summary": "Batch Get Accounts", "operationId": "batchGetDirectoryAccounts", "parameters": [ { "description": "account ids", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.BatchRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.DirectoryRecordListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/directory/groups/{id}/members": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "directory" ], "summary": "Directory group members", "operationId": "getDirectoryGroupMembers", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.StringListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/directory/tenants/resolve": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Resolve a tenant by id or code — exactly one of the two query params is required, id wins if both are supplied. Returns the tenant's full record; note tenant.code is a shared join SECRET, so a caller resolving by code has already proven they hold it, but the field should not be re-echoed into a channel the customer can read.", "produces": [ "application/json" ], "tags": [ "directory" ], "summary": "Resolve Tenant", "operationId": "resolveDirectoryTenant", "parameters": [ { "type": "string", "description": "tenant UUID", "name": "id", "in": "query" }, { "type": "string", "description": "tenant join code", "name": "code", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TenantResolveResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/email-templates": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Templates visible to the caller: tenant admins see the system defaults plus their own tenant's overrides, admins see every template across every tenant.", "produces": [ "application/json" ], "tags": [ "email-templates" ], "summary": "List", "operationId": "listEmailTemplates", "parameters": [ { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TemplatePageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "email-templates" ], "summary": "Create email template", "operationId": "createEmailTemplate", "parameters": [ { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_emailtemplates.WriteInput" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TemplateResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/email-templates/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One template by id, system default or tenant override.", "produces": [ "application/json" ], "tags": [ "email-templates" ], "summary": "Get", "operationId": "getEmailTemplate", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TemplateResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "put": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "email-templates" ], "summary": "Update email template", "operationId": "updateEmailTemplate", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_emailtemplates.WriteInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TemplateResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Remove a template. ResourceAuth write: tenant admins may delete their own tenant's overrides; only admins may delete a system default (tenant_id NULL).", "produces": [ "application/json" ], "tags": [ "email-templates" ], "summary": "Delete", "operationId": "deleteEmailTemplate", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/fulfillments": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a payment intent — a \"send\" (sender defaults to the caller) or, when sender_user_id or sender_wallet names someone else, a \"request\" the caller becomes the receiver of. deadline is required RFC3339. memo is the join key to on-chain settlement: 409 memo_taken if it's already held by a live (pending/claimed/submitted) fulfillment in the tenant — omit it and the server mints one. 422 amount_over_limit if a DIRECT-tagged payment exceeds the per-payment cap (max_uoa/max_cents echoed in the error body).\n\n**idempotency_key (optional, 8..255 chars) — pass one if your client can retry.** A second create with the same key in the same tenant returns the ORIGINAL fulfillment, same id, instead of minting a second payment. The key is durable for the row's whole life, so a retry that arrives after the original settled still resolves to it — that is the \"response was lost, client retried\" case. Without a key, behaviour is unchanged: every call creates a new payment intent. Note the counterparty notification fires only on the real create, never on a replay.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "Create Fulfillment", "operationId": "createFulfillment", "parameters": [ { "description": "fulfillment", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.CreateFulfillmentRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.FulfillmentResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "memo_taken — the supplied memo is already in use by a live (pending/claimed/submitted) fulfillment in this tenant. memo is the join key to on-chain settlement; omit it and the server mints one.", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "422": { "description": "amount_over_limit — a DIRECT-tagged payment over the per-payment cap (max_uoa + max_cents in payload)", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/fulfillments/{id}/status": { "get": { "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "Get Fulfillment Status", "operationId": "getFulfillmentStatus", "parameters": [ { "type": "string", "description": "fulfillment id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.FulfillmentStatusResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/group-types": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Search the caller's visible group-type catalog: global types (tenant_id NULL, the admin-managed cross-tenant set) plus the caller's own tenant's types, in one list. q matches name or description.", "produces": [ "application/json" ], "tags": [ "group-types" ], "summary": "List", "operationId": "listGroupTypes", "parameters": [ { "type": "string", "description": "search name or description", "name": "q", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.GroupTypePageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "group-types" ], "summary": "Create group type", "operationId": "createGroupType", "parameters": [ { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_grouptypes.CreateInput" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.GroupTypeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/group-types/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One group type by id — 404 if it doesn't exist, regardless of whether it's global or tenant-scoped (existence, not authorization, gates this read).", "produces": [ "application/json" ], "tags": [ "group-types" ], "summary": "Get", "operationId": "getGroupType", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.GroupTypeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Deletes a group type. Groups referencing it are NOT deleted or blocked — the FK is ON DELETE SET NULL, so they fall back to untyped rather than failing the delete or cascading.", "produces": [ "application/json" ], "tags": [ "group-types" ], "summary": "Delete", "operationId": "deleteGroupType", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "group-types" ], "summary": "Update group type", "operationId": "updateGroupType", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_grouptypes.UpdateInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.GroupTypeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/groups": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Every group in the caller's tenant (the policy's baseline group-read rule — any authenticated member of a tenant may list its groups). q searches name/description, type_id filters to one group_type, sort is name (A-Z, default) | name_desc | recent | oldest.", "produces": [ "application/json" ], "tags": [ "groups" ], "summary": "List", "operationId": "listGroups", "parameters": [ { "type": "string", "description": "search name or description", "name": "q", "in": "query" }, { "type": "string", "description": "name (A-Z, default) | name_desc | recent | oldest", "name": "sort", "in": "query" }, { "type": "string", "description": "filter by group type id", "name": "type_id", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.GroupPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Any authenticated member creates a group in their own tenant. 400 invalid_group_type if type_id is set but doesn't name a type visible to the caller (global or their tenant's).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "groups" ], "summary": "Create group", "operationId": "createGroup", "parameters": [ { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_groups.CreateInput" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.GroupResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/groups/summary": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Two modes: the default returns group-entity counts (created-when, size) bucketed by group_by=visibility|size_band; metric=joins instead returns membership JOIN events over time (group_id narrows to one group's joins). metric=joins counts joins ONLY, never net membership — account_groups rows are hard-deleted on removal, so a leave leaves nothing to count and the series can only ever climb. Net membership requires the group.member_added/group.member_removed audit events instead, and only from when those began recording. An unrecognized metric value is a 400 unsupported_metric rather than silently falling back to group counts.", "produces": [ "application/json" ], "tags": [ "groups" ], "summary": "Summary", "operationId": "summarizeGroups", "parameters": [ { "type": "string", "description": "joins — membership join events instead of groups", "name": "metric", "in": "query" }, { "enum": [ "visibility", "size_band" ], "type": "string", "description": "bucket dimension (ignored when metric=joins)", "name": "group_by", "in": "query" }, { "type": "string", "format": "uuid", "description": "with metric=joins: only joins into this group", "name": "group_id", "in": "query" }, { "type": "string", "description": "search name or description", "name": "q", "in": "query" }, { "type": "string", "description": "RFC3339 lower bound (inclusive)", "name": "since", "in": "query" }, { "type": "string", "description": "RFC3339 upper bound (exclusive)", "name": "until", "in": "query" }, { "type": "string", "description": "hour | day | week | month — returns data.series", "name": "interval", "in": "query" }, { "type": "string", "description": "IANA time zone for bucketing (default UTC)", "name": "tz", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Response" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/groups/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One group by id (ResourceAuth read — baseline: any tenant member may read any group in their tenant). 404 group_not_found if it doesn't exist; no separate 403 for cross-tenant since the baseline rule already scopes visibility.", "produces": [ "application/json" ], "tags": [ "groups" ], "summary": "Get", "operationId": "getGroup", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.GroupResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Deletes a group (ResourceAuth write: the group's creator, its tenant's admin, or a system admin). Membership rows are removed with it.", "produces": [ "application/json" ], "tags": [ "groups" ], "summary": "Delete", "operationId": "deleteGroup", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Updates a group's name/description/type (ResourceAuth write: creator, tenant admin, or system admin). 400 invalid_group_type if type_id doesn't resolve to a type the caller's tenant can use.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "groups" ], "summary": "Update group", "operationId": "updateGroup", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_groups.UpdateInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.GroupResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/groups/{id}/members": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "groups" ], "summary": "List group members", "operationId": "listGroupMembers", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "search members by email / username / first / last name", "name": "q", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AccountPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Adds one account to a group by account_id (ResourceAuth write on the group). 403 cross_tenant_member if the target account is not in the group's tenant — group membership never spans tenants.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "groups" ], "summary": "Add Member", "operationId": "addGroupMember", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "member", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.MemberRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/groups/{id}/members/{account_id}": { "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Removes one account from a group by account_id. 404 membership_not_found if the pair doesn't exist as a membership — this endpoint does not distinguish \"no such group\" from \"not a member\".", "produces": [ "application/json" ], "tags": [ "groups" ], "summary": "Remove Member", "operationId": "removeGroupMember", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "account_id", "name": "account_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/health": { "get": { "description": "Reports the db plus every configured peer (mb, kv), each as a bare \"ok\"/\"error\" keyed by role — never by implementation. Wire dashboards/alerting here, NOT the readiness probe (use /health/ready, so a peer blip can't 503 auth). Public (no auth). Any failing check yields \"degraded\" with a 503.", "produces": [ "application/json" ], "tags": [ "health" ], "summary": "Deep health check", "operationId": "healthCheck", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.HealthStatusResponse" } }, "503": { "description": "degraded — one or more checks failing", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.HealthStatusResponse" } } } } }, "/health/ready": { "get": { "description": "Gates traffic on the hard dependency only (db). Peer services (mb, kv) are deliberately excluded — a downstream blip must not 503 the whole API; they remain visible on GET /health. Public (no auth). Returns \"degraded\" with a 503 when the db is unreachable.", "produces": [ "application/json" ], "tags": [ "health" ], "summary": "Readiness probe", "operationId": "healthReady", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.HealthStatusResponse" } }, "503": { "description": "degraded — db unreachable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.HealthStatusResponse" } } } } }, "/me/audit-events": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "audit" ], "summary": "My recent activity", "operationId": "listMyAuditEvents", "parameters": [ { "type": "string", "description": "filter by action (e.g. person.updated)", "name": "action", "in": "query" }, { "type": "string", "description": "filter by resource type (e.g. person)", "name": "resource_type", "in": "query" }, { "type": "string", "description": "filter by resource id", "name": "resource_id", "in": "query" }, { "type": "string", "description": "created_at \u003e= (RFC3339 or YYYY-MM-DD)", "name": "from", "in": "query" }, { "type": "string", "description": "created_at \u003c= (RFC3339 or YYYY-MM-DD)", "name": "to", "in": "query" }, { "type": "string", "description": "recent (newest first, default) | oldest", "name": "sort", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuditEventPageResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/contacts/unseen-counts": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Per-counterparty unacked sent + received tallies over live fulfillments (contact-dot source). Pass the SAME created_after the bell summary + drill-down list use (e.g. the 48h window) or contacts show ghost dots for ancient unseen rows the user can't see anywhere. Omit for lifetime counts.", "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "Per-contact Unseen Counts", "operationId": "getMyContactUnseenCounts", "parameters": [ { "type": "string", "description": "RFC3339 timestamp; only count fulfillments created at/after this instant (match the bell/list window)", "name": "created_after", "in": "query" }, { "type": "string", "description": "sent|received|all (same semantics as /me/fulfillments)", "name": "direction", "in": "query" }, { "enum": [ "include", "exclude", "only" ], "type": "string", "description": "pay-yourself fulfillments (sender == receiver): include keeps them (default), exclude hides them (match the bell/list filter or contacts show ghost dots), only returns just them", "name": "self_payments", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ContactUnseenCountsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/fulfillments": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "List My Fulfillments", "operationId": "listMyFulfillments", "parameters": [ { "type": "string", "description": "sent|received|all", "name": "direction", "in": "query" }, { "type": "string", "description": "pending|confirmed|... or `outstanding` (= pending+claimed+submitted) or `closed` (= cancelled+declined+expired, the Declined tab)", "name": "status", "in": "query" }, { "type": "string", "description": "scope to fulfillments with one counterparty (the other party, per the caller's role)", "name": "counterparty_id", "in": "query" }, { "type": "string", "description": "recent (newest first, default) | oldest", "name": "sort", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" }, { "type": "string", "description": "RFC3339 timestamp; only fulfillments created at/after this instant (e.g. 48h window)", "name": "created_after", "in": "query" }, { "type": "string", "description": "RFC3339 timestamp; inclusive upper bound — pair with created_after for a bounded window", "name": "created_before", "in": "query" }, { "enum": [ "p2p", "deposit", "billpay", "direct", "reward", "terminal" ], "type": "string", "description": "narrow to one product line: p2p (no machine tag — a real person-to-person transfer) | deposit | billpay | direct | reward | terminal (a POS sale)", "name": "kind", "in": "query" }, { "type": "string", "description": "match reference LIKE '\u003cprefix\u003e%'; narrows the caller's own rows, never widens them. A service that stamps its own reference uses this to recover a create whose response was lost.", "name": "reference_prefix", "in": "query" }, { "enum": [ "include", "exclude", "only" ], "type": "string", "description": "pay-yourself fulfillments (sender == receiver: bill-pay funding, quick pays, self-sends): include keeps them (default), exclude hides them, only returns just them", "name": "self_payments", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.FulfillmentPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/fulfillments/ack": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Set/clear the caller's read-receipt (type=seen, default) or the receiver paid attestation (type=paid) on a list of fulfillment ids in one request. Ownership is enforced per id; ids the caller isn't a party to are skipped. acknowledged defaults to true.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "Bulk-acknowledge Fulfillments", "operationId": "bulkAckMyFulfillments", "parameters": [ { "description": "ids + ack type", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.BulkAckFulfillmentsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.BulkAckFulfillmentsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/fulfillments/ack-all": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Mark the caller's read-receipt (type=seen, default) or the receiver paid attestation (type=paid) on EVERY live fulfillment matching the filter — no id list, no page cap — so \"mark all seen\" clears badges beyond the loaded page. Filter axes (direction / contact / created_after window / self_payments) mirror the per-contact unseen-count badge, so the ack clears exactly what the badge counts. Idempotent; returns the number newly acknowledged.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "Acknowledge ALL matching Fulfillments", "operationId": "ackAllMyFulfillments", "parameters": [ { "description": "ack type + optional filter", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AckAllFulfillmentsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.BulkAckFulfillmentsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/fulfillments/summary": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Dashboard totals split by role (as_sender / as_receiver), each with outstanding + completed buckets and unseen counts.", "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "My Fulfillment Summary", "operationId": "getMyFulfillmentSummary", "parameters": [ { "type": "string", "description": "RFC3339 timestamp; when set, totals count only fulfillments created at/after this instant (e.g. 48h window). Omit for lifetime totals.", "name": "created_after", "in": "query" }, { "enum": [ "include", "exclude", "only" ], "type": "string", "description": "pay-yourself fulfillments (sender == receiver): include keeps them (default), exclude hides them (the alerts bell), only returns just them", "name": "self_payments", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.FulfillmentSummaryResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/fulfillments/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "Get My Fulfillment", "operationId": "getMyFulfillment", "parameters": [ { "type": "string", "description": "fulfillment id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.FulfillmentResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/fulfillments/{id}/ack": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Sets the caller's own read-receipt: type=seen (default) stamps sender_seen_at or receiver_seen_at depending on which party the caller is; type=paid stamps receiver_paid_ack_at and is receiver-only. A caller who is not a party to the fulfillment (or requests type=paid as the sender) gets 404, not 403. Idempotent set/clear, not a toggle.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "Acknowledge Fulfillment", "operationId": "ackFulfillment", "parameters": [ { "type": "string", "description": "fulfillment id", "name": "id", "in": "path", "required": true }, { "description": "ack type", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AckFulfillmentRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.FulfillmentResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/fulfillments/{id}/decline": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Payer refuses an incoming payment request. Caller must be the fulfillment's sender_user_id (403 otherwise) and the row must still be status=pending — once it has moved to submitted, paid, or any terminal state this returns 409 not_pending rather than acting. On success the row moves to declined.", "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "Decline Fulfillment", "operationId": "declineFulfillment", "parameters": [ { "type": "string", "description": "fulfillment id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.FulfillmentResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "not_pending — already submitted/paid, no longer declinable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/fulfillments/{id}/recall": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Creator withdraws (cancels) a fulfillment they created, while it is still pending or claimed. Caller must be created_by_user_id (403 otherwise).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "Recall Fulfillment", "operationId": "recallFulfillment", "parameters": [ { "type": "string", "description": "fulfillment id", "name": "id", "in": "path", "required": true }, { "description": "recall reason", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RecallFulfillmentRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.FulfillmentResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/fulfillments/{id}/submit": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Records that the payer has broadcast the on-chain payment, moving the intent pending→submitted so it drops out of the payable set immediately. Idempotent: acking a payment that has ALREADY landed (the settlement webhook routinely confirms the row before this call arrives) returns 200 with the current record, not an error. 409 is reserved for a row that moved on for another reason — a different payer claimed it, or it expired/declined/cancelled/failed.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "fulfillments" ], "summary": "Submit Fulfillment (payer broadcast)", "operationId": "submitFulfillment", "parameters": [ { "type": "string", "description": "fulfillment id", "name": "id", "in": "path", "required": true }, { "description": "broadcast tx hash", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SubmitFulfillmentRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.FulfillmentResponse" } }, "400": { "description": "invalid_tx_hash — tx_hash absent or not a 0x-prefixed 32-byte hex hash", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "not_pending — another payer claimed it, or the row is terminal; NOT returned for the caller's own already-settled payment", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/person": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "person" ], "summary": "Get my person", "operationId": "getMyPerson", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "person" ], "summary": "Deactivate my account", "operationId": "deactivateMyAccount", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonCascadeResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "person" ], "summary": "Update my person", "operationId": "updateMyPerson", "parameters": [ { "description": "profile fields", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.UpdatePersonRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonUpdateResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/person/accounts": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "person" ], "summary": "List my accounts", "operationId": "listMyPersonAccounts", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.MyAccountListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/wallets": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "wallets" ], "summary": "List my wallets", "operationId": "listMyWallets", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.WalletListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "wallets" ], "summary": "Create a wallet", "operationId": "createMyWallet", "parameters": [ { "description": "wallet", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.CreateWalletRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.WalletResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/wallets/multisig": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "wallets" ], "summary": "My wallets' multisig posture", "operationId": "myWalletsMultisig", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.WalletMultisigListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/wallets/{id}": { "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "wallets" ], "summary": "Remove a wallet", "operationId": "removeMyWallet", "parameters": [ { "type": "string", "description": "wallet id", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "wallets" ], "summary": "Update a wallet", "operationId": "updateMyWallet", "parameters": [ { "type": "string", "description": "wallet id", "name": "id", "in": "path", "required": true }, { "description": "fields to change", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.UpdateWalletRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.WalletResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/me/wallets/{id}/primary": { "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "wallets" ], "summary": "Promote a wallet to primary", "operationId": "setMyPrimaryWallet", "parameters": [ { "type": "string", "description": "wallet id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.WalletListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/oauth/clients": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Every client registered at this authorization server, newest first. `include_disabled=true` also returns deregistered ones. Platform admin only.", "produces": [ "application/json" ], "tags": [ "oauth" ], "summary": "List OAuth clients", "operationId": "listOauthClients", "parameters": [ { "type": "boolean", "description": "include deregistered clients", "name": "include_disabled", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OAuthClientPageResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/oauth/clients/{client_id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Disables a registered client: every subsequent /authorize and /token for this `client_id` fails as though it had never been registered. The row is retained for audit. Already-disabled and never-existed both answer 404. Does NOT revoke tokens the client already holds — those are ordinary enforcer tokens with their own expiry. Platform admin only.", "produces": [ "application/json" ], "tags": [ "oauth" ], "summary": "Deregister an OAuth client", "operationId": "deleteOauthClient", "parameters": [ { "type": "string", "description": "client_id to deregister", "name": "client_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.MessageResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/persons/lookup": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "person" ], "summary": "Lookup person by email or phone", "operationId": "lookupPerson", "parameters": [ { "type": "string", "description": "email", "name": "email", "in": "query" }, { "type": "string", "description": "phone", "name": "phone", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonLookupResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/phone/risk": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Twilio Lookup v2 risk for an arbitrary E.164 number. Elevated roles only (tenant_admin/admin/developer).", "produces": [ "application/json" ], "tags": [ "phone-risk" ], "summary": "Phone risk by number", "operationId": "getPhoneRiskByNumber", "parameters": [ { "type": "string", "description": "E.164 phone number", "name": "phone", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PhoneRiskResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/policies": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Custom Rego policies visible to the caller: every GLOBAL policy (tenant_id null — world-readable by design) plus the caller's own tenant's policies. Does not include the built-in static policy.rego engine, which every request runs regardless.", "produces": [ "application/json" ], "tags": [ "policies" ], "summary": "List policies", "operationId": "listPolicies", "parameters": [ { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PolicyPageResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Compiles and stores a new custom Rego policy under the fixed enforcer.custom package, live immediately with no restart — every replica compiles and caches it by content hash on first evaluation, not at deploy time. The module is UNTRUSTED CODE by construction: network/host builtins (http.send, net.lookup_ip_addr, opa.runtime) are stripped, so a policy referencing them fails to compile rather than being allowed to exfiltrate accessor data or reach the cluster network. A policy with no tenant_id (global, consumable by every tenant) requires the admin role — 403 forbidden otherwise for a tenant_admin caller.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "policies" ], "summary": "Create policy", "operationId": "createPolicy", "parameters": [ { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_policies.WriteInput" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PolicyResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/policies/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One custom policy's stored Rego source and metadata. Readable per the same global-plus-own-tenant visibility as listPolicies.", "produces": [ "application/json" ], "tags": [ "policies" ], "summary": "Get policy", "operationId": "getPolicy", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PolicyResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "put": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Recompiles the stored Rego source in place, same untrusted-code constraints as createPolicy. Write access is role-gated, not ownership-gated: tenant_write for the policy's own tenant, cross_tenant (admin) for a global one — the row's creator (created_by) is provenance only and grants no standing write access, unlike the normal \"write your own row\" baseline, because a policy is executable authorization logic other tenants may consume.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "policies" ], "summary": "Update policy", "operationId": "updatePolicy", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_policies.WriteInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PolicyResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Deletes a compiled custom Rego policy from the live authorization engine. Any subsequent POST /authz/check that still names this policy_id falls through to the built-in static policy (policy.rego) rather than erroring — a deleted policy silently stops narrowing/widening decisions rather than breaking the check endpoint.", "produces": [ "application/json" ], "tags": [ "policies" ], "summary": "Delete policy", "operationId": "deletePolicy", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/referrals/claim": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "referrals" ], "summary": "Claim a referral code", "operationId": "claimReferral", "parameters": [ { "description": "code to claim", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ClaimCodeRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ReferralClaimResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/referrals/invited": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Accounts that joined on the caller's referral code, newest first, each with kyc_verified. ?kyc=true|false filters (total follows the filter); the top-level kyc_verified rollup always counts ALL invitees who finished KYC — user-facing invite counters must render that number, never raw signups.", "produces": [ "application/json" ], "tags": [ "referrals" ], "summary": "List my invited users", "operationId": "listReferralInvited", "parameters": [ { "type": "boolean", "description": "filter: true = KYC-verified only, false = not-yet-verified only", "name": "kyc", "in": "query" }, { "type": "integer", "description": "limit (default 50, max 200)", "name": "limit", "in": "query" }, { "type": "integer", "description": "offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ReferralInvitedResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/referrals/join/{code}": { "get": { "produces": [ "application/json" ], "tags": [ "referrals" ], "summary": "Look up a public referral share link", "operationId": "getReferralByCode", "parameters": [ { "type": "string", "description": "code", "name": "code", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ReferralPublicJoinResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/referrals/my-code": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "referrals" ], "summary": "Get my referral code", "operationId": "getMyReferralCode", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ReferralCodeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/referrals/stats": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "referrals" ], "summary": "Get my referral stats", "operationId": "getReferralStats", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ReferralStatsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/roles": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The static role catalog (built-in + custom), open to ANY authenticated caller with no admin gate — this is the \"populate a role picker\" read, distinct from adminListRoles (GET /admin/roles) which serves the same rows behind the tenant_read admin gate for role administration. Small and unpaginated: total is the full row count and limit/offset describe the single page returned.", "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "List Roles", "operationId": "listRoles", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.RolePageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/sso-connections": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "sso-connections" ], "summary": "List SSO connections", "operationId": "listSSOConnections", "parameters": [ { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SSOConnectionPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "sso-connections" ], "summary": "Create SSO connection", "operationId": "createSSOConnection", "parameters": [ { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_ssoconnections.CreateInput" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SSOConnectionResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/sso-connections/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "sso-connections" ], "summary": "Get SSO connection", "operationId": "getSSOConnection", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SSOConnectionResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "sso-connections" ], "summary": "Delete SSO connection", "operationId": "deleteSSOConnection", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "sso-connections" ], "summary": "Update SSO connection", "operationId": "updateSSOConnection", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_ssoconnections.UpdateInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SSOConnectionResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/support/contact": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Submit a support message. Creates a support ticket and emails the tenant's support inbox; the returned ticket_id resolves at GET /tickets/{id}.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "support" ], "summary": "Contact customer service", "operationId": "contactSupport", "parameters": [ { "description": "support message", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SupportContactRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SupportContactResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/telemetry/auth-events": { "post": { "description": "Unauthenticated ingest for auth-funnel events from callers with no account context yet — the population that cannot emit ordinary client telemetry. event must be one of otp_requested, otp_send_failed, otp_verify_failed, login_failed; anything else is a 400 rather than a stored row, because a free-text event on an unauthenticated write would let anyone mint rows a support feed then displays as fact. The email is stored HASHED (for lookup) and MASKED (for reading), never in the clear. Well-formed requests answer 202 whether or not a row was written — an unknown tenant_code is dropped silently so this cannot be used to probe which tenant codes exist. Per-IP rate limited.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "telemetry" ], "summary": "Record a pre-auth attempt", "operationId": "recordAuthAttempt", "parameters": [ { "description": "the attempt", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthAttemptRequest" } } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/telemetry/events": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Ingests one client diagnostic event from the calling app (PWA/mobile). Fire-and-forget: returns 202 immediately — the structured server log is the primary record, this table only backs the admin read endpoints. source and event are both required in the body; an event with either blank is rejected 400.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "telemetry" ], "summary": "Record", "operationId": "recordTelemetryEvents", "parameters": [ { "description": "events", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_telemetry.RecordInput" } } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TelemetryRecordedResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tenants": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Tenants visible to the caller: a platform admin sees every tenant, a tenant admin sees their own, anyone else sees none. q searches name or code; status filters active/inactive/suspended. Each tenant's code (the join secret) is present only for a platform admin or that tenant's own tenant_admin — every other caller gets it stripped to null, not omitted.", "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "List", "operationId": "listTenants", "parameters": [ { "type": "string", "description": "search name or code", "name": "q", "in": "query" }, { "enum": [ "active", "inactive", "suspended" ], "type": "string", "description": "filter by status", "name": "status", "in": "query" }, { "enum": [ "name", "name_desc", "recent", "oldest" ], "type": "string", "default": "name", "description": "sort order", "name": "sort", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TenantPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Provisions a new tenant. System-admin only — 403 for any other caller, since there is no existing tenant row yet for a resource-level check to apply to.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "Create", "operationId": "createTenant", "parameters": [ { "description": "tenant", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_tenants.CreateInput" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TenantResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tenants/self-serve": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "Self-Serve Create Tenant", "operationId": "selfServeTenant", "parameters": [ { "description": "tenant name", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SelfServeTenantRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.AuthResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tenants/summary": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One metric row per tenant the caller may read: accounts, active accounts, KYC-verified accounts, groups, pending invites and last signup — the platform-console view that replaces a list-then-N-counts loop. Scoped by the SAME compiled row filter as GET /tenants, so a tenant admin sees exactly their own tenant's row and a platform admin sees every tenant; a non-admin caller simply gets one row (their own), never an error.", "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "Summary", "operationId": "summarizeTenants", "parameters": [ { "type": "integer", "description": "page size (default 50, max 200)", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TenantSummaryResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tenants/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One tenant's full configuration: branding, app/payment-link URLs, auth and wallet provider, join policy, status. code (the join secret) is redacted to null unless the caller is a platform admin or that tenant's own tenant_admin — same redaction rule as listTenants.", "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "Get tenant", "operationId": "getTenant", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TenantResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Soft-deletes a tenant. System-admin only. Irreversible in the sense that PATCH {status:\"inactive\"} — a reversible deactivation — is almost certainly what you want instead.", "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "Delete Tenant", "operationId": "deleteTenant", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Partial update of tenant configuration (branding, URLs, join policy, status, etc.) — only fields present in the body change. Behind a manage-level resource check (tenant admins may update their own tenant; platform admins any tenant).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "Update", "operationId": "updateTenant", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "tenant fields", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_tenants.UpdateInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TenantResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tenants/{id}/auth-provider": { "put": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "Set Auth Provider", "operationId": "setTenantAuthProvider", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "auth provider", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_tenants.AuthProviderInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TenantResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tenants/{id}/code": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Replaces the tenant's join code with a freshly generated one and returns it in the response body (the only time the new value is shown in full). The OLD code stops working immediately for anyone trying to join with it — every join link and any invite text that embeds the old code goes stale, so this is a \"the help-desk is about to get join-code tickets\" action, not a routine rotation.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "Rotate Code", "operationId": "generateTenantCode", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TenantCodeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tenants/{id}/invites": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "List the tenant's invites. Callers with tenant authority see all invites; regular members see only the ones they sent.", "produces": [ "application/json" ], "tags": [ "invites" ], "summary": "List", "operationId": "listTenantInvites", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "type": "boolean", "description": "tenant-wide management view (manage-role only)", "name": "all", "in": "query" }, { "type": "string", "description": "filter by status: pending | accepted | expired | cancelled", "name": "status", "in": "query" }, { "type": "string", "description": "filter by invitee email (case-insensitive substring)", "name": "email", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.InvitePageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Invite an email into the tenant. Any member of the tenant may send an invite; callers without tenant authority always invite at the \"user\" role (passing another role returns 403).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "invites" ], "summary": "Create", "operationId": "createTenantInvite", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "invite", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.CreateInviteRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.InviteResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "email already belongs to a member of this tenant", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tenants/{id}/invites/summary": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Visibility mirrors GET /tenants/{id}/invites EXACTLY: caller-scoped to invites they sent by default, tenant-wide only with all=true from a manage-role caller. That asymmetry is an email-PII boundary — a summary that counted tenant-wide rows for a self-scoped caller would disclose how many invites other people sent, and its total would contradict the list it drills into. status filters pending|accepted|expired|cancelled; email is a case-insensitive substring match.", "produces": [ "application/json" ], "tags": [ "invites" ], "summary": "Invite summary", "operationId": "summarizeInvites", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "type": "boolean", "description": "tenant-wide management view (manage-role only)", "name": "all", "in": "query" }, { "type": "string", "description": "filter by status: pending | accepted | expired | cancelled", "name": "status", "in": "query" }, { "type": "string", "description": "filter by invitee email (case-insensitive substring)", "name": "email", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.InviteSummaryResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tenants/{id}/invites/{inviteId}": { "delete": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Cancels a pending invite before it is accepted — an already-accepted, expired, or already-cancelled invite is a 404, not a no-op. Behind the tenant manage gate (developer role and up); a plain member who SENT the invite cannot cancel it themselves.", "produces": [ "application/json" ], "tags": [ "invites" ], "summary": "Cancel invite", "operationId": "cancelTenantInvite", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "inviteId", "name": "inviteId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.OKResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tenants/{id}/modules": { "put": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Replaces the tenant's HALO-Lego module entitlements — which product surfaces this tenant has BOUGHT (V3-02). Values are group slugs prefixed `module_` (`module_work`, `module_money`); the prefix is required, because after these are unioned into the accessor's group slugs it is the only thing separating them from identity groups like `contractor`. A REPLACE, not a patch: send the full desired set. **System-admin only** — a tenant_admin passes the route's manage check but must not be able to grant their own tenant a module, which is writing their own invoice. Every leaf's entitlement gate fails CLOSED, so removing a module closes those surfaces on the next resolve.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tenants" ], "summary": "Set module entitlements", "operationId": "setTenantModules", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "the full desired module set", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_tenants.ModulesInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TenantResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/terms": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Every terms document row the caller may read (admin: all; tenant admin: their tenant's + global), including inactive and expired versions — this is the admin history view, not the \"what applies right now\" view (that's getMyTerms). Unfiltered beyond role scope: no type/active/tenant query params exist yet.", "produces": [ "application/json" ], "tags": [ "terms" ], "summary": "List", "operationId": "listTerms", "parameters": [ { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TermsListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Creates a NEW terms document version. This does NOT deactivate or supersede any existing active version of the same type — setTermsActive is a separate, explicit step. Until the old version is turned off, getMyTerms' current-version resolution treats both as active and picks between them (tenant-specific over global, otherwise the newest-effective), so a caller may keep seeing the version they already accepted. content_hash is computed server-side (sha256 of content) and is what an acceptance snapshots, not a client-supplied value. tenant_id is admin-only; a tenant_admin caller is silently pinned to their own tenant regardless of what they pass.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "terms" ], "summary": "Create", "operationId": "createTerms", "parameters": [ { "description": "terms document", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.CreateTermsRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TermsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/terms/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "One terms document by id. Cross-tenant and unauthorized reads collapse to 404, not 403 — a foreign tenant's document id is indistinguishable from a nonexistent one, so this is never a cross-tenant existence oracle.", "produces": [ "application/json" ], "tags": [ "terms" ], "summary": "Get terms document", "operationId": "getTermsById", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TermsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/terms/{id}/active": { "put": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Flips one document's is_active flag. There is no enforced \"one active version per type\" invariant — activating a new version leaves any previously-active version of the same type active too, and deactivating a still-accepted mandatory document silently drops the onboarding gate for everyone who was blocked on it. A tenant admin may only toggle documents owned by their own tenant; global (tenant_id null) documents are admin-only, since toggling one changes the gate for every tenant at once.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "terms" ], "summary": "Set Active", "operationId": "setTermsActive", "parameters": [ { "type": "string", "description": "id", "name": "id", "in": "path", "required": true }, { "description": "active flag", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SetActiveTermsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TermsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tickets": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Row-filtered by role: users see their own tickets, developers and tenant admins their tenant's, admins all.", "produces": [ "application/json" ], "tags": [ "tickets" ], "summary": "List tickets", "operationId": "listTickets", "parameters": [ { "type": "string", "description": "open | pending | resolved | closed", "name": "status", "in": "query" }, { "type": "string", "description": "low | normal | high | urgent", "name": "priority", "in": "query" }, { "type": "string", "description": "assignee account id", "name": "assignee", "in": "query" }, { "type": "boolean", "description": "true = assignee IS NULL (the real queue); cannot combine with assignee", "name": "unassigned", "in": "query" }, { "type": "string", "description": "requester account id", "name": "requester", "in": "query" }, { "type": "string", "description": "exact source: api | support_contact | automated (program-filed, e.g. the PWA's Plaid auto-ticket) | email", "name": "source", "in": "query" }, { "type": "string", "description": "'#1042' / '1042' = ticket number (exact); a UUID = ticket id (exact); anything else searches the subject", "name": "q", "in": "query" }, { "type": "string", "description": "updated_at_desc (default) | updated_at_asc (longest-waiting first) | created_at_desc | created_at_asc", "name": "sort", "in": "query" }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketPageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Create a ticket (with its first message) as the authenticated account. Notifies the tenant's support inbox.\n\nSupport staff (a `tenant_read` holder in the tenant, i.e. the `developer` role and up) may pass `requester_account_id` to open the ticket ON BEHALF OF another account in the same tenant — the agent-on-a-call path. The ticket then belongs to that customer, so `GET /tickets?requester=` finds it and the customer's own owner-baseline read can see it; the first message is still authored by the agent who typed it. A non-staff caller passing someone else's id gets 403, and an unknown or cross-tenant id gets 400.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tickets" ], "summary": "Open a support ticket", "operationId": "createTicket", "parameters": [ { "description": "ticket", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tickets/summary": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Counts the caller-visible tickets per status under the SAME filters as GET /tickets (status itself is ignored — every status is reported). One query, no page cap: `?unassigned=true\u0026source=support_contact` is the true human queue depth, however deep it is.", "produces": [ "application/json" ], "tags": [ "tickets" ], "summary": "Ticket counts by status", "operationId": "ticketSummary", "parameters": [ { "type": "string", "description": "low | normal | high | urgent", "name": "priority", "in": "query" }, { "type": "string", "description": "assignee account id", "name": "assignee", "in": "query" }, { "type": "boolean", "description": "true = assignee IS NULL", "name": "unassigned", "in": "query" }, { "type": "string", "description": "requester account id", "name": "requester", "in": "query" }, { "type": "string", "description": "exact source: api | support_contact | automated | email", "name": "source", "in": "query" }, { "type": "string", "description": "same semantics as GET /tickets", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketSummaryResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tickets/{id}": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "produces": [ "application/json" ], "tags": [ "tickets" ], "summary": "Get a ticket", "operationId": "getTicket", "parameters": [ { "type": "string", "description": "ticket id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Change status, priority, or assignment. Manage-gated: developers, tenant admins, and admins — requesters cannot reach this route.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tickets" ], "summary": "Update a ticket (staff)", "operationId": "updateTicket", "parameters": [ { "type": "string", "description": "ticket id", "name": "id", "in": "path", "required": true }, { "description": "changes", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketUpdateRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tickets/{id}/attachments/{file_id}/url": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Mint a short-lived presigned URL for a file attached to this ticket. The file must sit on one of the ticket's messages; internal-note attachments are staff-only. The URL is a bearer link — fetch it promptly and re-request after expiry.", "produces": [ "application/json" ], "tags": [ "tickets" ], "summary": "Presign an attachment download", "operationId": "ticketAttachmentURL", "parameters": [ { "type": "string", "description": "ticket id", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "attached file id", "name": "file_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketAttachmentURLResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tickets/{id}/close": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Requester self-service close (staff may use it too). Idempotent.", "produces": [ "application/json" ], "tags": [ "tickets" ], "summary": "Close a ticket", "operationId": "closeTicket", "parameters": [ { "type": "string", "description": "ticket id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/tickets/{id}/messages": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Oldest first. Internal staff notes are visible to staff only.", "produces": [ "application/json" ], "tags": [ "tickets" ], "summary": "List a ticket's thread", "operationId": "listTicketMessages", "parameters": [ { "type": "string", "description": "ticket id", "name": "id", "in": "path", "required": true }, { "type": "integer", "description": "page size", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketMessagePageResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Append a message. internal=true is staff-only. Public replies drive the lifecycle: a requester reply reopens, a staff reply marks the ticket pending, and each notifies the other side.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tickets" ], "summary": "Reply on a ticket", "operationId": "addTicketMessage", "parameters": [ { "type": "string", "description": "ticket id", "name": "id", "in": "path", "required": true }, { "description": "message", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketMessageRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.TicketMessageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/verification/group-challenge": { "post": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "verification" ], "summary": "Initiate a verification group challenge", "operationId": "verificationGroupChallenge", "parameters": [ { "description": "request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/enforcer-v3_internal_usecase_verifications.GroupChallengeInput" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ChallengeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "429": { "description": "challenge_in_progress — same-type async challenge initiated within the last 10s; honour Retry-After", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/verification/person": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The caller's person-level verifications (KYC packets, attestations), cross-tenant by construction because they hang off the person, not the account. Self-scoped: a filter narrows this set and can never reach another person's rows. With NO query string the response is the legacy `{success, data:[...], count}` shape, every row, submitted_at DESC — unchanged. With `limit` or `offset` the response is the ADR 0003 envelope `{success, data:{items, total, filtered, limit, offset}}`; `limit=0` returns counts alone. Filters or a sort WITHOUT `limit`/`offset` return the legacy shape over the filtered, sorted rows. `status`/`kind`/`issuer` are comma-separated ORs; an unrecognised member matches nothing. `q` is a case-insensitive substring over id, issuer and decision_reason — the row only; the person is not searched because the list is already one person's. `from`/`to` bound the column named by `date_field` (default submitted_at): `YYYY-MM-DD` is an inclusive whole UTC day, RFC3339 an exact instant (`to` exclusive); a row with no value in that column is excluded when a bound is set and included otherwise. `since`/`until` and `created_after`/`created_before` are aliases. Nullable sort columns (decided, expires) order NULLS LAST in both directions; every sort tiebreaks on id. An unknown query KEY is `400 unknown_param`.", "produces": [ "application/json" ], "tags": [ "verification" ], "summary": "List my person verifications", "operationId": "listPersonVerifications", "parameters": [ { "type": "string", "description": "csv of statuses, OR'd (pending, approved, rejected, withdrawn, expired); unknown members match nothing", "name": "status", "in": "query" }, { "type": "string", "description": "csv of kinds, OR'd (free-form column: identity, kyc, ...)", "name": "kind", "in": "query" }, { "type": "string", "description": "csv of issuers, OR'd (self, acme, ...)", "name": "issuer", "in": "query" }, { "type": "string", "description": "case-insensitive substring over id, issuer, decision_reason", "name": "q", "in": "query" }, { "enum": [ "submitted", "decided", "expires" ], "type": "string", "default": "submitted", "description": "which timestamp from/to bound", "name": "date_field", "in": "query" }, { "type": "string", "description": "date_field \u003e= this (YYYY-MM-DD = start of that UTC day, or RFC3339)", "name": "from", "in": "query" }, { "type": "string", "description": "date_field \u003c this (YYYY-MM-DD = end of that UTC day inclusive, or RFC3339 exclusive)", "name": "to", "in": "query" }, { "enum": [ "submitted", "decided", "created", "status", "kind", "expires" ], "type": "string", "default": "submitted", "description": "sort field", "name": "sort", "in": "query" }, { "enum": [ "asc", "desc" ], "type": "string", "default": "desc", "description": "sort direction", "name": "sort_dir", "in": "query" }, { "type": "integer", "description": "page size 1..200 (clamped); 0 = counts only; absent = unpaged legacy shape", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset \u003e= 0", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "paged envelope (legacy {success,data:[],count} when limit/offset absent)", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.PersonVerificationsPageResponse" } }, "400": { "description": "unknown_param | invalid_limit | invalid_offset | invalid_from | invalid_to | invalid_window", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/verification/sessions": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "The caller's own verification sessions (one row per provider and type). Self-scoped: a filter narrows this set and can never reach another account's rows. With NO query string the response is the legacy `{success, data:[...], count}` shape, every row, provider ASC — unchanged for existing clients. With `limit` or `offset` the response is the ADR 0003 envelope `{success, data:{items, total, filtered, limit, offset}}`: `total` is the caller's row count before filters, `filtered` after, `items` one page; `limit=0` returns the counts alone. Filters or a sort WITHOUT `limit`/`offset` return the legacy shape over the filtered, sorted rows. `status`/`type`/`provider` are comma-separated ORs; an unrecognised member matches nothing (never a 400). `q` is a case-insensitive substring match over session_id, provider, status and last_error. `from`/`to` bound \"last moved\" = verified_at, else updated_at: `YYYY-MM-DD` is an inclusive whole UTC day, RFC3339 an exact instant (`to` exclusive); malformed is a 400. `since`/`until` and `created_after`/`created_before` are accepted as aliases. Every sort tiebreaks on id in the same direction, so pages never repeat or skip a row. An unknown query KEY is `400 unknown_param`.", "produces": [ "application/json" ], "tags": [ "verification" ], "summary": "List my verification sessions", "operationId": "listVerificationSessions", "parameters": [ { "type": "string", "description": "csv of statuses, OR'd (pending, active, verified, failed, expired, revoked); unknown members match nothing", "name": "status", "in": "query" }, { "type": "string", "description": "csv of verification types, OR'd (kyc, kyb, tax_id_selfie, ...)", "name": "type", "in": "query" }, { "type": "string", "description": "csv of provider slugs, OR'd (cybrid, activecampaign, ...)", "name": "provider", "in": "query" }, { "type": "string", "description": "case-insensitive substring over session_id, provider, status, last_error", "name": "q", "in": "query" }, { "type": "string", "description": "last-moved \u003e= this (YYYY-MM-DD = start of that UTC day, or RFC3339)", "name": "from", "in": "query" }, { "type": "string", "description": "last-moved \u003c this (YYYY-MM-DD = end of that UTC day inclusive, or RFC3339 exclusive)", "name": "to", "in": "query" }, { "enum": [ "created", "updated", "status", "type", "attempts" ], "type": "string", "default": "updated", "description": "sort field", "name": "sort", "in": "query" }, { "enum": [ "asc", "desc" ], "type": "string", "default": "desc", "description": "sort direction", "name": "sort_dir", "in": "query" }, { "type": "integer", "description": "page size 1..200 (clamped); 0 = counts only; absent = unpaged legacy shape", "name": "limit", "in": "query" }, { "type": "integer", "description": "page offset \u003e= 0", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "paged envelope (legacy {success,data:[],count} when limit/offset absent)", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.SessionsPageResponse" } }, "400": { "description": "unknown_param | invalid_limit | invalid_offset | invalid_from | invalid_to | invalid_window", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/verification/summary": { "get": { "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Counts of the verification sessions (KYC/KYB and whatever else is provider-configured) the caller may read — never more than their own account visibility already grants, so a plain user's summary covers only their own sessions, a tenant admin's their tenant's. group_by=status uses the full six-state lifecycle (pending, active, verified, failed, expired, revoked), not just verified/failed/pending. type and provider are open query filters, not closed enums — they pass through to whatever a tenant's connection is actually configured with. since/until bound the totals and any bucket dimension too, not just interval series, so a dashboard tile scoped to a window never reports a lifetime count.", "produces": [ "application/json" ], "tags": [ "verification" ], "summary": "Summary", "operationId": "summarizeVerifications", "parameters": [ { "enum": [ "status", "type", "provider" ], "type": "string", "description": "bucket dimension", "name": "group_by", "in": "query" }, { "enum": [ "pending", "active", "verified", "failed", "expired", "revoked" ], "type": "string", "description": "filter by session status", "name": "status", "in": "query" }, { "enum": [ "kyc", "kyb" ], "type": "string", "description": "filter by verification type", "name": "type", "in": "query" }, { "type": "string", "description": "filter by provider", "name": "provider", "in": "query" }, { "type": "string", "description": "RFC3339 lower bound on created_at (inclusive)", "name": "since", "in": "query" }, { "type": "string", "description": "RFC3339 upper bound on created_at (exclusive)", "name": "until", "in": "query" }, { "type": "string", "description": "hour | day | week | month — returns data.series", "name": "interval", "in": "query" }, { "type": "string", "description": "IANA time zone for bucketing (default UTC)", "name": "tz", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Response" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } } } } }, "/webhooks/alchemy/{tenant_id}/routed": { "post": { "description": "Terminates Alchemy Custom (GraphQL) webhook deliveries for the Base RouterV2 `Routed` event and the GpvTracker `GPVRecorded` event (fee/plan-hash enrichment), republishing each occurrence onto its settlement topic. The path keeps its historical /routed name — one webhook carries both events. Authenticated by the X-Alchemy-Signature HMAC over the raw body — NOT by enforcer bearer/API-key auth. Returns 200 for anything Alchemy should not retry (including unparseable or foreign payloads), 401 on a missing/invalid signature, and 503 only for a transient publish failure that warrants redelivery. Success and 401/503 bodies are plain status text; only the 400 is JSON.", "consumes": [ "application/json" ], "tags": [ "webhooks" ], "summary": "Alchemy settlement webhook (Routed + GPVRecorded)", "operationId": "alchemyWebhookRouted", "parameters": [ { "type": "string", "description": "tenant UUID the webhook is registered under", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "hex-encoded HMAC-SHA256 of the raw request body, keyed with the tenant's Alchemy signing key", "name": "X-Alchemy-Signature", "in": "header", "required": true } ], "responses": { "200": { "description": "accepted (or dropped as non-retryable)", "schema": { "type": "string" } }, "400": { "description": "malformed tenant_id", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "missing or invalid signature", "schema": { "type": "string" } }, "413": { "description": "payload exceeds the server body limit", "schema": { "type": "string" } }, "503": { "description": "transient publish failure — Alchemy should redeliver", "schema": { "type": "string" } } } } }, "/webhooks/cdp/{tenant_id}/gpv": { "post": { "description": "Terminates Coinbase/CDP (Hook0) webhook deliveries for the `GPVRecorded` event and republishes the raw body onto the GPV topic. Authenticated by the X-Hook0-Signature header (HMAC verified against the tenant's sealed gpv_secret, 5m/30s replay window) — NOT by enforcer bearer/API-key auth. Same status contract as the Routed edge: 200 for anything CDP should not retry, 401 on a bad signature, 503 only for a transient publish failure. Success and 401/503 bodies are plain status text; only the 400 is JSON.", "consumes": [ "application/json" ], "tags": [ "webhooks" ], "summary": "CDP settlement webhook (GPVRecorded)", "operationId": "cdpWebhookGPV", "parameters": [ { "type": "string", "description": "tenant UUID the webhook is registered under", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "Hook0 signature: t=\u003cunix seconds\u003e,h=\u003cspace-separated signed header names\u003e,v1=\u003chex HMAC-SHA256 over t.h.values.body\u003e", "name": "X-Hook0-Signature", "in": "header", "required": true } ], "responses": { "200": { "description": "accepted", "schema": { "type": "string" } }, "400": { "description": "malformed tenant_id", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "missing, invalid, or replay-window-expired signature", "schema": { "type": "string" } }, "413": { "description": "payload exceeds the server body limit", "schema": { "type": "string" } }, "503": { "description": "transient publish failure — CDP should redeliver", "schema": { "type": "string" } } } } }, "/webhooks/cdp/{tenant_id}/routed": { "post": { "description": "Terminates Coinbase/CDP (Hook0) webhook deliveries for the RouterV2 `Routed` event and republishes the raw, pre-decoded body onto the settlement topic. Authenticated by the X-Hook0-Signature header (HMAC verified against the tenant's sealed secret, 5m/30s replay window) — NOT by enforcer bearer/API-key auth. Returns 200 for anything CDP should not retry, 401 on a missing/invalid/expired signature, and 503 only for a transient publish failure that warrants redelivery. Success and 401/503 bodies are plain status text; only the 400 is JSON.", "consumes": [ "application/json" ], "tags": [ "webhooks" ], "summary": "CDP settlement webhook (Routed)", "operationId": "cdpWebhookRouted", "parameters": [ { "type": "string", "description": "tenant UUID the webhook is registered under", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "Hook0 signature: t=\u003cunix seconds\u003e,h=\u003cspace-separated signed header names\u003e,v1=\u003chex HMAC-SHA256 over t.h.values.body\u003e", "name": "X-Hook0-Signature", "in": "header", "required": true } ], "responses": { "200": { "description": "accepted", "schema": { "type": "string" } }, "400": { "description": "malformed tenant_id", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "missing, invalid, or replay-window-expired signature", "schema": { "type": "string" } }, "413": { "description": "payload exceeds the server body limit", "schema": { "type": "string" } }, "503": { "description": "transient publish failure — CDP should redeliver", "schema": { "type": "string" } } } } }, "/webhooks/quicknode/{tenant_id}/routed": { "post": { "description": "Terminates QuickNode (Streams/QuickAlerts) webhook deliveries carrying raw EVM logs, ABI-decodes Base RouterV2 `Routed` and GpvTracker `GPVRecorded` occurrences, and republishes each canonical body onto its settlement topic. Authenticated by the x-qn-* header set: x-qn-signature = hex HMAC-SHA256(token, nonce + contentHash + timestamp), with sha256(body) additionally required to equal x-qn-content-hash and the timestamp bound to a 5m/30s replay window — NOT enforcer bearer/API-key auth. Returns 200 for anything QuickNode should not retry (including payloads with no Routed logs), 401 on any signature/content-hash/timestamp failure, and 503 only for a transient publish failure that warrants redelivery. Success and 401/503 bodies are plain status text; only the 400 is JSON.", "consumes": [ "application/json" ], "tags": [ "webhooks" ], "summary": "QuickNode settlement webhook (Routed + GPVRecorded)", "operationId": "quicknodeWebhookRouted", "parameters": [ { "type": "string", "description": "tenant UUID the webhook is registered under", "name": "tenant_id", "in": "path", "required": true }, { "type": "string", "description": "hex HMAC-SHA256 over nonce + contentHash + timestamp, keyed with the destination's security token", "name": "x-qn-signature", "in": "header", "required": true }, { "type": "string", "description": "per-delivery nonce", "name": "x-qn-nonce", "in": "header", "required": true }, { "type": "string", "description": "SHA-256 hex of the payload (must match the delivered body)", "name": "x-qn-content-hash", "in": "header", "required": true }, { "type": "string", "description": "unix seconds; must fall inside the 5m past / 30s future replay window", "name": "x-qn-timestamp", "in": "header", "required": true } ], "responses": { "200": { "description": "accepted (or dropped as non-retryable)", "schema": { "type": "string" } }, "400": { "description": "malformed tenant_id", "schema": { "$ref": "#/definitions/internal_delivery_http_handler.ErrorResponse" } }, "401": { "description": "missing/invalid signature, content-hash mismatch, or stale timestamp", "schema": { "type": "string" } }, "413": { "description": "payload exceeds the server body limit", "schema": { "type": "string" } }, "503": { "description": "transient publish failure — QuickNode should redeliver", "schema": { "type": "string" } } } } } }, "definitions": { "enforcer-v3_internal_authz.VerificationRef": { "type": "object", "properties": { "external_customer_id": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "type": { "description": "kyc | kyb", "type": "string" } } }, "enforcer-v3_internal_domain_account.Account": { "type": "object", "properties": { "active": { "type": "boolean" }, "authenticated_at": { "type": "string" }, "claimed_at": { "type": "string" }, "created_at": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "first_name": { "type": "string" }, "id": { "type": "string" }, "invited_by": { "type": "string" }, "is_discoverable": { "description": "IsDiscoverable gates whether this account can be added as a linked contact\nby others in the same tenant. Defaults true (see migration 000022).", "type": "boolean" }, "last_active_at": { "description": "warm-path activity, throttled", "type": "string" }, "last_login_at": { "type": "string" }, "last_name": { "type": "string" }, "passkey_mfa_verified_at": { "description": "PasskeyMfaVerifiedAt stamps when the SERVER observed, via the Privy\nmanagement API, that this account's passkey MFA enrollment is complete\n(factor advertised + a linked credential backing it). NULL = never\nverified. Written only by SetPasskeyMfaVerified from the\n/auth/me/passkey/verify flow — the client's own view of Privy state is\neventually consistent and must never be the source of this stamp.", "type": "string" }, "person": { "$ref": "#/definitions/enforcer-v3_internal_domain_person.Person" }, "person_id": { "type": "string" }, "privy_user_id": { "type": "string" }, "profile_completed": { "type": "boolean" }, "provisioned_via": { "description": "ProvisionedVia is how this membership came to exist (migration 000088):\nProvisionedViaPortalToken marks a SHELL ACCOUNT minted by a cold portal\nlink; nil is an ordinary signup (every row that predates the column).\nClaimedAt is when a verified login by the same person bound a credential\nto a shell; nil on an unclaimed shell and on every non-shell row.", "type": "string" }, "role": { "description": "Preloaded relations.", "allOf": [ { "$ref": "#/definitions/enforcer-v3_internal_domain_role.Role" } ] }, "role_id": { "type": "string" }, "tenant": { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.Tenant" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" }, "username": { "type": "string" }, "wallet_address": { "type": "string" }, "wallet_send_migrated_at": { "description": "WalletSendMigratedAt stamps when this account's smart wallet had the\nmandatory app-key owner quorum attached (wallet-send-enforcement). NULL =\nnot yet migrated; the login-heal signals the PWA to prompt for the\none-time owner-change authorization when the tenant is send-enforced.", "type": "string" } } }, "enforcer-v3_internal_domain_apikey.APIKey": { "type": "object", "properties": { "account_id": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "key_prefix": { "type": "string" }, "last_used_at": { "type": "string" }, "name": { "type": "string" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_audit.Event": { "type": "object", "properties": { "action": { "type": "string" }, "actor_account_id": { "description": "nil = system/unauthenticated", "type": "string" }, "created_at": { "type": "string" }, "external_session_id": { "description": "ExternalSessionID is the identity PROVIDER's session (Privy's `sid`),\npopulated only when the actor authenticated with a raw provider token and\ntherefore holds no enforcer session (migration 000071). Exactly one of\nSessionID / ExternalSessionID is ever set; both nil means the credential\nhas no session at all (API key, portal link, service principal, worker).\n\nIt is deliberately NOT merged into SessionID: that column joins to\nrefresh_tokens, and a provider session never will.", "type": "string" }, "id": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" }, "session_id": { "description": "SessionID is the login session the actor was acting under (migration\n000069). Callers do not set it: Record fills it from the request context,\nso every emitter gets session attribution without knowing sessions exist.\n\nNil is normal and carries meaning — the action was taken with a credential\nthat is not a session (API key, portal link, raw provider bearer, service\nprincipal) or by a background worker. Do not read nil as \"unknown\".", "type": "string" }, "tenant_id": { "type": "string" } } }, "enforcer-v3_internal_domain_authattempt.Event": { "type": "object", "properties": { "account_id": { "description": "AccountID is NULL for the normal case — a caller who cannot log in has no\naccount context. It is populated only where the server could resolve one\nanyway, and its absence is never an error.", "type": "string" }, "client_ip": { "type": "string" }, "context": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "email_masked": { "description": "EmailMasked is enough to recognize an address in a feed, not enough to be\nan address list if the table leaks.", "type": "string" }, "event": { "type": "string" }, "id": { "type": "string" }, "message": { "type": "string" }, "tenant_id": { "type": "string" }, "user_agent": { "type": "string" } } }, "enforcer-v3_internal_domain_connection.Capability": { "type": "object", "properties": { "created_at": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_connection.Provider": { "type": "object", "properties": { "capability": { "$ref": "#/definitions/enforcer-v3_internal_domain_connection.Capability" }, "capability_id": { "type": "string" }, "created_at": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_connection.TenantConnection": { "type": "object", "properties": { "config": { "description": "Config is the decrypted credential map — populated only on authorized\nsingle-row reads, never on lists.", "type": "object", "additionalProperties": {} }, "created_at": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "provider": { "$ref": "#/definitions/enforcer-v3_internal_domain_connection.Provider" }, "provider_app_id": { "description": "ProviderAppID is the provider's PUBLIC application id (e.g. the Privy app id).\nPlaintext (not in the sealed config) so it can be queried for login tenant\nresolution and served to the client SDK. app_secret stays in config_encrypted.", "type": "string" }, "provider_id": { "type": "string" }, "send_enforcement": { "description": "SendEnforcement marks this connection's tenant as wallet-send-enforced\n(multi-sig): the tenant's Privy smart wallets get the mandatory app-key\nowner quorum and rwa's signing gateway enforces send policy. It lives on\nthe connection row — the mode is baggage of the cybrid-bank wiring for\nspecific tenants, not a property of every Privy tenant. Plaintext (not in\nthe sealed config) so operators flip it with one UPDATE. A tenant is\nenforced iff ANY active connection row carries the flag; when rotating the\nflagged connection, set it on the replacement row or enforcement drops.", "type": "boolean" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_contact.Contact": { "type": "object", "properties": { "active": { "type": "boolean" }, "alerts": { "description": "Alerts is a computed field populated on list/get for LINKED contacts: the\ncaller's unacked fulfillment (send/receive) tallies with that contact,\nread from enforcer-cybrid and keyed on the shared account id. Best-effort —\nnil when the fulfillment service is unconfigured or unreachable, or when\nthe contact has no outstanding activity. Acks happen against cybrid; this\nis read-only badge data. Never stored.", "allOf": [ { "$ref": "#/definitions/enforcer-v3_internal_domain_contact.ContactAlerts" } ] }, "avatar_url": { "description": "AvatarURL is the resolved picture the client should render: the owner's\nCustomAvatarURL override when set, else the linked person's own\nprofile_image_url. Computed on list/get so the PWA has ONE field to read\nand never has to implement the precedence itself. Never stored.", "type": "string" }, "blacklisted": { "type": "boolean" }, "contact_account_id": { "type": "string" }, "contact_type": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "custom_avatar_url": { "description": "CustomAvatarURL is the OWNER's private picture override for this contact\n(migration 000057). Meaningful on both contact types: on a linked contact\nit shadows the linked person's own profile_image_url, on a custom contact\nit is the only picture there is. nil = no override.", "type": "string" }, "custom_email": { "type": "string" }, "custom_first_name": { "type": "string" }, "custom_last_name": { "type": "string" }, "custom_phone_number": { "type": "string" }, "custom_wallet_address": { "description": "CustomWalletAddress is a manually-entered pay-to wallet on a custom contact\n(custom contacts have no account to derive WalletAddress from). Ported from\nv2; only custom contacts ever set it.", "type": "string" }, "description": { "type": "string" }, "email": { "type": "string" }, "favorite_rank": { "description": "FavoriteRank orders the owner's favorite contacts: nil = not favorited,\n1 = first favorite. A user may hold MANY favorites — the rank is a\nper-owner ordering, not a single slot (unique per owner among non-null\nranks, see migration 000056). Favorites float to the top of every list.", "type": "integer" }, "first_name": { "type": "string" }, "id": { "type": "string" }, "last_name": { "type": "string" }, "my_account_id": { "type": "string" }, "name": { "type": "string" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "username": { "description": "FirstName/LastName/Email are computed display fields populated by the\ncontacts usecase on list/get: for linked contacts from the contact's\naccount, for custom contacts mirrored from the custom_* columns. This\ngives the PWA one uniform name/email shape per row (matching the legacy\ncontacts list) without a second lookup. Never stored.\nUsername is the linked contact's account handle (@username), populated on\nlist/get so the PWA can show @handle instead of falling back to email.\nCustom contacts have no account, so it stays nil. Never stored.", "type": "string" }, "wallet_address": { "description": "WalletAddress is a computed field populated by the contacts usecase for\nlinked contacts — the embedded wallet of the contact's account. Never\nstored in the contacts table; loaded from accounts on list/get.", "type": "string" } } }, "enforcer-v3_internal_domain_contact.ContactAlerts": { "type": "object", "properties": { "received_unseen": { "type": "integer" }, "sent_unseen": { "type": "integer" }, "total": { "type": "integer" } } }, "enforcer-v3_internal_domain_device.DeviceType": { "type": "object", "properties": { "code": { "type": "string" }, "created_at": { "type": "string" }, "display_name": { "type": "string" }, "id": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_device.PersonDevice": { "type": "object", "properties": { "app_identifier": { "type": "string" }, "app_version": { "type": "string" }, "created_at": { "type": "string" }, "device_id": { "type": "string" }, "device_name": { "type": "string" }, "device_type": { "$ref": "#/definitions/enforcer-v3_internal_domain_device.DeviceType" }, "device_type_id": { "type": "string" }, "id": { "type": "string" }, "key_algorithm": { "type": "string" }, "last_seen_at": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "os_name": { "type": "string" }, "os_version": { "type": "string" }, "person_id": { "type": "string" }, "public_key": { "description": "PublicKey is the base64 Ed25519 key the device signs check-ins with,\ntrusted on first registration (TOFU). KeyAlgorithm names the scheme.", "type": "string" }, "push_token": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_emailtemplate.Template": { "type": "object", "properties": { "body_template": { "type": "string" }, "created_at": { "type": "string" }, "format": { "type": "string" }, "id": { "type": "string" }, "subject": { "type": "string" }, "template_id": { "type": "string" }, "tenant_id": { "description": "nil = system default", "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_fulfillment.CompletedSummary": { "type": "object", "properties": { "count": { "type": "integer" }, "total_notional_uoa": { "type": "string" }, "total_paid_uoa": { "type": "string" }, "unseen_count": { "type": "integer" } } }, "enforcer-v3_internal_domain_fulfillment.ContactUnseenCount": { "type": "object", "properties": { "contact_user_id": { "type": "string" }, "received_unseen": { "type": "integer" }, "sent_unseen": { "type": "integer" } } }, "enforcer-v3_internal_domain_fulfillment.DeliveryLeg": { "type": "object", "properties": { "bps": { "type": "integer" }, "delivered": { "description": "Delivered is base units of Token, read from the receipt's Transfer logs\n(the chain publishes it nowhere else). Empty when not resolved.", "type": "string" }, "token": { "type": "string" }, "wallet": { "type": "string" } } }, "enforcer-v3_internal_domain_fulfillment.DirectedSummary": { "type": "object", "properties": { "completed": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.CompletedSummary" }, "outstanding": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.OutstandingSummary" }, "unseen_count": { "type": "integer" } } }, "enforcer-v3_internal_domain_fulfillment.Fulfillment": { "type": "object", "properties": { "block_number": { "type": "integer" }, "chain_id": { "type": "integer" }, "claimed_at": { "type": "string" }, "created_at": { "type": "string" }, "created_by_user_id": { "type": "string" }, "deadline": { "type": "string" }, "declined_at": { "type": "string" }, "declined_by_user_id": { "type": "string" }, "deleted_at": { "type": "string" }, "delivery_legs": { "description": "DeliveryLegs is what the RECEIVER got, which no on-chain event reports —\nsee migration 000077. Neither Routed nor GPVRecorded carries an output\ntoken or amount, and the Router's per-leg distribution emits nothing, so\nthis is resolved from Book.getPlan plus the receipt's Transfer logs.\n\nPlanVerified gates it: only TRUE means our re-hash matched the event's\nplanHash and the legs are exact. FALSE means inferred (the plan changed\nunder us, or an unrecoverable inlinePlan) and NULL means never attempted.\nNeither is \"probably fine\" — 25.6% of settled rows on prod were paid under\na plan that has since changed, because a receiver can rewrite their own\nplan at will (Book.setPlan is ungated on msg.sender).", "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.DeliveryLeg" } }, "expected_plan_hash": { "type": "string" }, "expired_at": { "type": "string" }, "fee_charged": { "type": "string" }, "id": { "type": "string" }, "idempotency_key": { "description": "IdempotencyKey de-duplicates CREATE (migration 000082). Optional: when a\ncaller supplies one, a second create with the same (tenant_id, key)\nreturns the ORIGINAL row instead of minting a second payment. Unique per\ntenant over non-NULL values, for the row's whole lifetime — a retry that\narrives after the original settled must still resolve to it, which is\nexactly the \"answer lost, client retried later\" case.", "type": "string" }, "input_spent_actual": { "type": "string" }, "input_token_actual": { "type": "string" }, "kind": { "description": "Kind is the product line this fulfillment belongs to: p2p | deposit |\nbillpay | direct | reward. Derived server-side from the reference tag at\ncreate (ClassifyKind) and stored, rather than re-derived per query from a\nfree-text column. Empty only on rows written before migration 000075 or by\na pod still on the previous image; the query layer falls back to the\nreference for those.", "type": "string" }, "max_fee_bps": { "type": "integer" }, "memo": { "description": "bytes32 on-chain memo — the join key between this record and chain state.", "type": "string" }, "notional_actual": { "type": "string" }, "notional_uoa": { "type": "string" }, "paid_uoa": { "description": "PaidUOA is the summed ROUTED settlements for this row's memo — what\nactually arrived, against NotionalUOA's what-was-owed. The excess is\nPaidUOA - NotionalUOA, and it is the reason this field exists: the\noverpaid filter finds rows where a payer routed the same memo twice or a\nroute declared more than the request asked for, but a boolean cannot tell\nsupport HOW MUCH.\n\nDERIVED, not a column (gorm:\"-\"): computed per page by the admin read\npaths. A POINTER because absent must stay distinguishable from zero — on\nany endpoint that does not compute it, a plain string would render \"0\",\nwhich reads as \"nothing ever arrived\" for a fully paid transfer.", "type": "string" }, "payer_address": { "type": "string" }, "plan_hash_actual": { "type": "string" }, "plan_verified": { "type": "boolean" }, "recall_reason": { "type": "string" }, "recalled_at": { "type": "string" }, "recalled_by_user_id": { "type": "string" }, "receiver": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.UserDisplay" }, "receiver_paid_ack_at": { "type": "string" }, "receiver_seen_at": { "type": "string" }, "receiver_user_id": { "type": "string" }, "receiver_wallet": { "type": "string" }, "reference": { "type": "string" }, "request_token": { "type": "string" }, "sender": { "description": "Populated by the usecase for authenticated endpoints — never stored.", "allOf": [ { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.UserDisplay" } ] }, "sender_cost_uoa": { "description": "SenderCostUOA is value_at_mid(input_spent_actual) - notional_uoa: what the\nroute cost the sender ABOVE what was delivered. fee_charged is only part\nof it — on the Aug-26 route the fee was 2.99 USDC and the true cost 13.18.\n\nSlippageUOA is the residual after the fee. ★ It is NOT always \"lost\": on a\nDIRECT same-token leg the principal never swaps, so the gap is a transfer\nto the RECEIVER rather than a loss to liquidity providers. Check\nDeliveryLegs before calling it a loss. Negative means the route beat mid,\nand it is stored signed so a better-than-mid execution is not clamped away.\n\nNULL means NOT COMPUTED — no pool for the input token, an RPC failure, or\na row predating migration 000081. It never means zero.", "type": "string" }, "sender_seen_at": { "type": "string" }, "sender_user_id": { "type": "string" }, "sender_wallet": { "type": "string" }, "settled_at": { "type": "string" }, "slippage_uoa": { "type": "string" }, "status": { "type": "string" }, "submitted_at": { "type": "string" }, "tenant_id": { "type": "string" }, "tx_hash": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_fulfillment.OutstandingSummary": { "type": "object", "properties": { "by_status": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.StatusBucket" } }, "count": { "type": "integer" }, "total_notional_uoa": { "type": "string" }, "unseen_count": { "type": "integer" } } }, "enforcer-v3_internal_domain_fulfillment.StatusBucket": { "type": "object", "properties": { "count": { "type": "integer" }, "status": { "description": "pending|claimed|submitted", "type": "string" }, "total_notional_uoa": { "type": "string" } } }, "enforcer-v3_internal_domain_fulfillment.StatusProjection": { "type": "object", "properties": { "id": { "type": "string" }, "notional_uoa": { "type": "string" }, "paid_sum": { "type": "string" }, "settled_at": { "type": "string" }, "status": { "type": "string" } } }, "enforcer-v3_internal_domain_fulfillment.Summary": { "type": "object", "properties": { "as_receiver": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.DirectedSummary" }, "as_sender": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.DirectedSummary" }, "user_id": { "type": "string" } } }, "enforcer-v3_internal_domain_fulfillment.TimeseriesBucket": { "type": "object", "properties": { "bucket": { "description": "Bucket is the period start, RFC3339 date (day/week) or month start.", "type": "string" }, "cancelled_count": { "description": "Cancelled folds cancelled | declined | expired — ended without payment.", "type": "integer" }, "cancelled_notional_uoa": { "type": "string" }, "received_count": { "type": "integer" }, "received_notional_uoa": { "type": "string" }, "sent_count": { "description": "Sent / Received count every non-cancelled row in the period.", "type": "integer" }, "sent_notional_uoa": { "type": "string" }, "settled_count": { "description": "Settled is the subset that actually moved money (status = confirmed).", "type": "integer" }, "settled_notional_uoa": { "type": "string" } } }, "enforcer-v3_internal_domain_fulfillment.UserDisplay": { "type": "object", "properties": { "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "first_name": { "type": "string" }, "is_contact": { "description": "IsContact is true when this counterparty is already a saved (linked)\ncontact of the caller viewing the row, so the PWA can badge it without a\nsecond lookup. Computed per-viewer; false for the caller themselves.", "type": "boolean" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "phone_number_verified": { "type": "boolean" }, "user_id": { "type": "string" }, "username": { "type": "string" }, "wallet_address": { "description": "WalletAddress is the counterparty's on-file wallet (from their account),\nso the row renders the send/receive wallet alongside the name.", "type": "string" } } }, "enforcer-v3_internal_domain_group.Group": { "type": "object", "properties": { "created_at": { "type": "string" }, "created_by": { "type": "string" }, "description": { "type": "string" }, "group_type_id": { "description": "GroupTypeID classifies the group; nil = untyped. Must reference a GLOBAL\ntype or one from the group's own tenant (enforced by the usecase).", "type": "string" }, "id": { "type": "string" }, "is_public": { "type": "boolean" }, "member_count": { "description": "MemberCount is computed on load, not stored.", "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_grouptype.GroupType": { "type": "object", "properties": { "created_at": { "type": "string" }, "created_by": { "type": "string" }, "description": { "type": "string" }, "group_count": { "description": "GroupCount is how many live groups use this type — computed on list\nreads (read-only column), never stored. The console used to pull 500\ngroups to count per type client-side; wrong past 500, wasteful before.", "type": "integer" }, "id": { "type": "string" }, "metadata": { "description": "Metadata carries client presentation hints (icon, color, ordering …);\nthe server never interprets it.", "type": "object", "additionalProperties": {} }, "name": { "type": "string" }, "slug": { "type": "string" }, "tenant_id": { "description": "nil = global", "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_identity.ProviderType": { "type": "string", "enum": [ "privy", "email_otp", "google", "siwe", "phone_otp", "passkey", "oidc", "saml" ], "x-enum-varnames": [ "ProviderPrivy", "ProviderEmailOTP", "ProviderGoogle", "ProviderSIWE", "ProviderPhoneOTP", "ProviderPasskey", "ProviderOIDC", "ProviderSAML" ] }, "enforcer-v3_internal_domain_invite.Invite": { "type": "object", "properties": { "accepted_account_id": { "type": "string" }, "accepted_at": { "type": "string" }, "created_at": { "type": "string" }, "email": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "invited_by": { "type": "string" }, "role": { "$ref": "#/definitions/enforcer-v3_internal_domain_role.Role" }, "role_id": { "type": "string" }, "status": { "type": "string" }, "tenant": { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.Tenant" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_invite.Summary": { "type": "object", "properties": { "acceptance_rate": { "description": "AcceptanceRate is Accepted / Resolved as a percentage, 1dp.\n\nDeliberately NOT accepted/total: a tenant that just sent 100 invites would\notherwise show ~0% acceptance purely because they are all still pending,\nwhich reads as failure rather than as \"too early to say\". Zero when nothing\nhas resolved yet.", "type": "number" }, "buckets": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Bucket" } }, "dimension": { "type": "string" }, "multi_valued": { "type": "boolean" }, "resolved": { "description": "Resolved is the count of invites that reached a terminal state\n(accepted + expired + cancelled), i.e. total minus still-pending.", "type": "integer" }, "series": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Point" } }, "total": { "type": "integer" }, "truncated": { "type": "boolean" } } }, "enforcer-v3_internal_domain_maildlq.Entry": { "type": "object", "properties": { "attempts": { "type": "integer" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "last_error": { "type": "string" }, "wire_topic": { "type": "string" } } }, "enforcer-v3_internal_domain_passkey.Credential": { "type": "object", "properties": { "account_id": { "type": "string" }, "attestation_type": { "type": "string" }, "backup_eligible": { "type": "boolean" }, "backup_state": { "type": "boolean" }, "created_at": { "type": "string" }, "friendly_name": { "type": "string" }, "id": { "type": "string" }, "last_used_at": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_person.CascadeResult": { "type": "object", "properties": { "accounts_soft_deleted": { "type": "integer" }, "devices_unregistered": { "type": "integer" }, "links_soft_deleted": { "type": "integer" }, "person_deleted": { "description": "PersonDeleted is false when the person row was KEPT because they still\nhold live accounts in other tenants. A tenant-scoped delete removes the\nmembership, not the human.", "type": "boolean" } } }, "enforcer-v3_internal_domain_person.Person": { "type": "object", "properties": { "created_at": { "type": "string" }, "dob": { "type": "string" }, "email_verified": { "type": "boolean" }, "first_name": { "type": "string" }, "home_address_line1": { "type": "string" }, "home_address_line2": { "type": "string" }, "home_city": { "type": "string" }, "home_country": { "type": "string" }, "home_place_id": { "description": "Home address — canonical, owned here (cybrid KYC + report-builder read it).\nHomePlaceID references an enforcer-geo place; the rest is a denormalized\nsnapshot so /auth/me serves the address without a geo round-trip.", "type": "string" }, "home_postal_code": { "type": "string" }, "home_region": { "type": "string" }, "id": { "type": "string" }, "last_name": { "type": "string" }, "name": { "description": "deprecated display name; prefer first_name/last_name", "type": "string" }, "phone_verified": { "type": "boolean" }, "primary_email": { "type": "string" }, "primary_phone": { "type": "string" }, "profile_image_url": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_personverification.JSONBMap": { "type": "object", "additionalProperties": {} }, "enforcer-v3_internal_domain_personverification.PersonVerification": { "type": "object", "properties": { "created_at": { "type": "string" }, "decided_at": { "description": "Decision fields populate together when an admin approves or rejects.\nDecidedBy FKs back to accounts.id — \"which admin made the call\" is an\naudit-trail concern, not an identity one.", "type": "string" }, "decided_by": { "type": "string" }, "decision_reason": { "type": "string" }, "expires_at": { "description": "ExpiresAt lets the background expiry job age out stale approvals (e.g. a\n1-year KYC). Nil = no expiry policy for this row.", "type": "string" }, "file_id": { "description": "FileID is a cross-service reference into enforcer-files (files moved out\nof the enforcer in v3), so there is no local FK. Pointer because not every\nverification has an attached document (issuer-attested booleans, on-chain\nproofs, etc.).", "type": "string" }, "id": { "type": "string" }, "issuer": { "description": "Issuer is the third party that produced the attestation. \"self\" for\nuser-submitted docs awaiting admin review.", "type": "string" }, "kind": { "description": "Kind is intentionally a free-form varchar (not an enum) so adding a new\nverification type doesn't require a migration. Operator policy lives at\nthe usecase layer.", "type": "string" }, "metadata": { "description": "Metadata is a free-form JSON bag for issuer-specific fields (document\ntype, sanctions-screen score, etc.).", "allOf": [ { "$ref": "#/definitions/enforcer-v3_internal_domain_personverification.JSONBMap" } ] }, "person_id": { "type": "string" }, "status": { "type": "string" }, "submitted_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_policy.Policy": { "type": "object", "properties": { "active": { "type": "boolean" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "source_sha": { "type": "string" }, "tenant_id": { "description": "nil = global", "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_referral.Code": { "type": "object", "properties": { "account_id": { "type": "string" }, "code": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "tenant_id": { "type": "string" } } }, "enforcer-v3_internal_domain_referral.InvitedUser": { "type": "object", "properties": { "account_id": { "type": "string" }, "active": { "type": "boolean" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "joined_at": { "type": "string" }, "kyc_verified": { "type": "boolean" }, "last_name": { "type": "string" }, "username": { "type": "string" } } }, "enforcer-v3_internal_domain_referral.LeaderRow": { "type": "object", "properties": { "account_id": { "type": "string" }, "active": { "type": "integer" }, "email": { "type": "string" }, "kyc_verified": { "type": "integer" }, "referred": { "type": "integer" }, "username": { "type": "string" } } }, "enforcer-v3_internal_domain_referral.Stats": { "type": "object", "properties": { "active": { "description": "of those, currently active", "type": "integer" }, "code": { "type": "string" }, "kyc_verified": { "description": "KycVerified is, of those, how many hold a verified kyc/kyb verification\nsession — the ONLY number user-facing invite counters should render\n(product rule: invite friends counts KYC'd users, never raw signups).", "type": "integer" }, "referred": { "description": "accounts whose invited_by is this account", "type": "integer" } } }, "enforcer-v3_internal_domain_role.Role": { "type": "object", "properties": { "admin_managed": { "type": "boolean" }, "created_at": { "type": "string" }, "cross_tenant": { "description": "Capability grants (additive; all false = baseline-only, like \"user\").", "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "tenant_manage": { "type": "boolean" }, "tenant_read": { "type": "boolean" }, "tenant_write": { "type": "boolean" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_sso.Connection": { "type": "object", "properties": { "config": { "description": "Config is the decrypted configuration — populated only on authorized\nsingle-row reads (with secret fields redacted), never on lists.", "type": "object", "additionalProperties": {} }, "created_at": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "provider_type": { "description": "ProviderType is identity.ProviderOIDC or identity.ProviderSAML.", "allOf": [ { "$ref": "#/definitions/enforcer-v3_internal_domain_identity.ProviderType" } ] }, "slug": { "description": "Slug is the human-friendly handle for the unauthenticated flow routes\n(/auth/sso/:connection/...). Globally unique among live rows — the flow\nresolves a connection with no tenant in hand. IdP-registered URLs\n(redirect_uri / ACS / entity id) always use the UUID so renames never\nbreak federation.", "type": "string" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_summary.Bucket": { "type": "object", "properties": { "count": { "type": "integer" }, "key": { "type": "string" }, "label": { "type": "string" }, "pct": { "type": "number" } } }, "enforcer-v3_internal_domain_summary.Data": { "type": "object", "properties": { "buckets": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Bucket" } }, "dimension": { "type": "string" }, "multi_valued": { "type": "boolean" }, "series": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Point" } }, "total": { "type": "integer" }, "truncated": { "type": "boolean" } } }, "enforcer-v3_internal_domain_summary.Point": { "type": "object", "properties": { "by": { "type": "object", "additionalProperties": { "type": "integer" } }, "count": { "type": "integer" }, "ts": { "type": "string" } } }, "enforcer-v3_internal_domain_summary.Response": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Data" }, "success": { "type": "boolean", "example": true }, "window": { "$ref": "#/definitions/enforcer-v3_internal_domain_summary.Window" } } }, "enforcer-v3_internal_domain_summary.Window": { "type": "object", "properties": { "interval": { "type": "string" }, "since": { "type": "string" }, "tz": { "type": "string" }, "until": { "type": "string" } } }, "enforcer-v3_internal_domain_telemetry.ClientEvent": { "type": "object", "properties": { "account_id": { "type": "string" }, "context": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "event": { "type": "string" }, "id": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "string" }, "tenant_id": { "type": "string" } } }, "enforcer-v3_internal_domain_tenant.JSONBMap": { "type": "object", "additionalProperties": {} }, "enforcer-v3_internal_domain_tenant.Summary": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.SummaryRow" } }, "total": { "type": "integer" } } }, "enforcer-v3_internal_domain_tenant.SummaryRow": { "type": "object", "properties": { "accounts": { "type": "integer" }, "active_accounts": { "type": "integer" }, "groups": { "type": "integer" }, "last_signup_at": { "description": "LastSignupAt is the newest account created_at, nil for an empty tenant.", "type": "string" }, "name": { "type": "string" }, "pending_invites": { "type": "integer" }, "status": { "type": "string" }, "tenant_id": { "type": "string" }, "verified": { "description": "Verified counts ACCOUNTS with a verified kyc/kyb session, not sessions —\nthe same predicate the contacts KYC gate and referral stats use, so the\nconsole and the gate agree on who is verified.", "type": "integer" } } }, "enforcer-v3_internal_domain_tenant.Tenant": { "type": "object", "properties": { "account_abstraction": { "type": "boolean" }, "allow_user_discovery": { "description": "AllowUserDiscovery gates contact discovery for the whole tenant: when true,\naccounts may be discoverable (and new accounts default to discoverable);\nwhen false, discovery is off tenant-wide regardless of account.is_discoverable.", "type": "boolean" }, "app_url": { "type": "string" }, "auth_provider": { "description": "AuthProvider / WalletProvider: nil = inherit the instance default.", "type": "string" }, "banner_url": { "type": "string" }, "billing_status": { "description": "BillingStatus is the tenant's platform-billing dunning state, PROJECTED\nfrom enforcer-billing (migration 000087): \"\" | active | past_due |\nrestricted | suspended | collections. enforcer-billing is the source of\ntruth; this is a copy the billing.status_changed consumer keeps current so\nthe value rides Accessor.billing_status on every resolve with no hop.\n\n\"\" means UNKNOWN and readers MUST treat it as active (fail open).\n\n`\u003c-:false` makes GORM never write these two columns: Repository.Update is\na whole-row Save, so without it an admin editing the tenant's name from a\nstale struct would silently roll the projection back. Only\nBillingStatusStore.ApplyBillingStatus writes them, by targeted UPDATE\nunder the monotonic entered_at guard.", "type": "string" }, "billing_status_entered_at": { "type": "string" }, "code": { "type": "string" }, "created_at": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "logo_url": { "type": "string" }, "metadata": { "description": "Metadata is a generic per-tenant jsonb bag (feature flags, extension config).", "allOf": [ { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.JSONBMap" } ] }, "metered_sends_enabled": { "description": "MeteredSendsEnabled turns on per-transaction limit metering: every value leg\nleaving the platform is measured against the caller's live cap before the\nserver co-signs. Meaningful only while Web3Enabled is true — the pair\n(false, true) is refused on write; see ValidateWeb3Gates.", "type": "boolean" }, "modules": { "description": "Modules is the tenant's MODULE entitlements as group slugs, prefixed\n`module_` (migration 000094, V3-02). Which HALO-Lego surfaces this tenant\nhas bought — NOT which of them any given account may use, which is the\nrole's question.\n\nIt lives on the tenant rather than in account_groups because it is a fact\nabout the TENANT: a module per account would mean auto-joining every new\naccount and would make \"remove one person from a module the tenant paid\nfor\" expressible. The resolver UNIONS this into Accessor.GroupSlugs, so\nevery leaf's RequireModule reads it with no new field and no extra hop.\n\nSame `\u003c-:false` guard and the same targeted-write rule as BillingStatus\nabove: Repository.Update is a whole-row Save, so without it an admin\nediting the tenant's name from a stale struct would silently revoke every\nmodule. Only ModuleStore writes these two columns.", "type": "array", "items": { "type": "string" } }, "modules_updated_at": { "type": "string" }, "name": { "type": "string" }, "payment_link_url": { "type": "string" }, "privy_app_id": { "type": "string" }, "self_join_policy": { "type": "string" }, "status": { "type": "string" }, "theme_colors": { "description": "ThemeColors is the tenant's colour palette — a `jsonb` column that has\nexisted since the identity schema (000001) and was never wired to a model\nfield, so nothing has ever read or written it.\n\nIt stays a loose map because the column is genuinely untyped and the KEY\nVOCABULARY is not defined yet: EPIC-002 RN-01 owns it, since the render\nmodule is the first real consumer and the set a PDF needs is the set worth\nagreeing on. Giving it a struct here would assert a shape the column does\nnot enforce and no writer produces.", "allOf": [ { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.JSONBMap" } ] }, "thumbnail_url": { "type": "string" }, "updated_at": { "type": "string" }, "wallet_provider": { "type": "string" }, "web3_enabled": { "description": "Web3Enabled is the tenant-wide web3 kill switch. False rejects EVERY web3\ntransaction for the tenant — guarded sends, signing, and RPC writes alike —\nso it is deliberately a gate rather than an enforcement mode. Defaults true\n(migration 000066) because false would disable web3 for every existing\ntenant on deploy.", "type": "boolean" } } }, "enforcer-v3_internal_domain_terms.Terms": { "type": "object", "properties": { "content": { "type": "string" }, "content_hash": { "type": "string" }, "created_at": { "type": "string" }, "effective_at": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "is_mandatory": { "type": "boolean" }, "summary": { "type": "string" }, "tenant_id": { "description": "nil = global", "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" }, "version": { "type": "string" } } }, "enforcer-v3_internal_domain_ticket.Message": { "type": "object", "properties": { "author_account_id": { "type": "string" }, "body": { "type": "string" }, "created_at": { "type": "string" }, "file_ids": { "description": "FileIDs are enforcer-files ids. Persisted now; the presigned-URL broker\nthat makes them readable cross-user is Phase 2 (docs/plans/ticket-api.md).", "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "internal": { "description": "Internal marks a staff-only note: never shown to the requester, never\nnotifies. The usecase fences both writing and reading it to staff.", "type": "boolean" }, "ticket_id": { "type": "string" } } }, "enforcer-v3_internal_domain_ticket.Ticket": { "type": "object", "properties": { "assignee_account_id": { "type": "string" }, "closed_at": { "type": "string" }, "created_at": { "type": "string" }, "external_key": { "description": "ExternalKey is the FILING SYSTEM's own id for the thing this ticket is\nabout — a payment id, a refund id — set only when a service raised it.\n\nIt exists because Kafka is at-least-once: a redelivered message, a DLQ\nreplay or two consumer replicas racing would each open a fresh ticket for\none payout, and three copies of a problem is worse than none — the second\nagent works a ticket the first already answered. Unique per tenant\n(partial index, migration 000090), so a re-file returns the existing row.\n\nRead-only to clients: a requester cannot claim a service's key.", "type": "string" }, "id": { "type": "string" }, "priority": { "type": "string" }, "requester_account_id": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "subject": { "type": "string" }, "tenant_id": { "type": "string" }, "ticket_number": { "description": "TicketNumber is the human reference (\"ticket #1042\") — DB-generated\nidentity, global across tenants (see migration 000061).", "type": "integer" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_domain_verification.JSONBMap": { "type": "object", "additionalProperties": {} }, "enforcer-v3_internal_domain_verification.Session": { "type": "object", "properties": { "account_id": { "type": "string" }, "attempt_count": { "type": "integer" }, "blocked_reason": { "type": "string" }, "can_retry": { "description": "Computed on read by Decorate, never stored. The server owns this policy:\na client that re-derives it from Status will get `expired` wrong (it is\nretryable) and will conflate `verified` with being blocked.", "type": "boolean" }, "challenge_data": { "$ref": "#/definitions/enforcer-v3_internal_domain_verification.JSONBMap" }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "external_customer_id": { "type": "string" }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "last_error": { "type": "string" }, "last_refreshed_at": { "type": "string" }, "last_used_at": { "type": "string" }, "metadata": { "$ref": "#/definitions/enforcer-v3_internal_domain_verification.JSONBMap" }, "provider": { "type": "string" }, "provider_id": { "type": "string" }, "rejection_scope": { "description": "RejectionScope names WHICH terminal state this is — ScopeVerification (this\ninquiry failed, re-sendable) or ScopeCustomer (the provider rejected the\ncustomer outright, nothing on our side lifts it). NULL/\"\" means the\nprovider never told us, which is every row written before migration 000093.", "type": "string" }, "remedy": { "type": "string" }, "response_data": { "$ref": "#/definitions/enforcer-v3_internal_domain_verification.JSONBMap" }, "session_id": { "type": "string" }, "session_type": { "type": "string" }, "status": { "type": "string" }, "status_history": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_verification.StatusTransition" } }, "tenant_id": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" }, "verification_guid": { "type": "string" }, "verified_at": { "type": "string" } } }, "enforcer-v3_internal_domain_verification.StatusTransition": { "type": "object", "properties": { "from": { "type": "string" }, "reason": { "type": "string" }, "timestamp": { "description": "unix seconds", "type": "integer" }, "to": { "type": "string" } } }, "enforcer-v3_internal_domain_walletaudit.Finding": { "type": "object", "properties": { "account_id": { "type": "string" }, "alerted_at": { "description": "AlertedAt stamps when this finding paged, so it pages once rather than every\npass. History is kept: a re-detected condition opens a NEW row, which is what\nmakes flapping visible instead of hidden behind one perpetually-open row.", "type": "string" }, "details": { "description": "Details is the evidence: the numbers that produced the verdict (threshold,\nauthorization_keys, user_is_member, the two quorum ids). Present so \"why is this\nflagged\" is answerable from the row alone, without re-reading the provider.", "allOf": [ { "$ref": "#/definitions/enforcer-v3_internal_domain_walletaudit.JSONBMap" } ] }, "first_detected_at": { "description": "FirstDetectedAt is the dwell clock the worklist sorts by. Preserved across\npasses — an upsert must never reset it, or a long-standing problem would look\nnew forever and nothing would ever appear old.", "type": "string" }, "id": { "type": "string" }, "last_seen_at": { "type": "string" }, "remedy": { "type": "string" }, "resolved_at": { "type": "string" }, "rule": { "type": "string" }, "severity": { "type": "string" }, "subject": { "type": "string" }, "summary": { "type": "string" }, "tenant_id": { "type": "string" } } }, "enforcer-v3_internal_domain_walletaudit.JSONBMap": { "type": "object", "additionalProperties": {} }, "enforcer-v3_internal_usecase_accounts.AdminSessionInfo": { "type": "object", "properties": { "client_ip": { "type": "string" }, "created_at": { "type": "string" }, "expires_at": { "description": "ExpiresAt is nil for a provider session — Privy owns that lifetime and\nnever tells us when it ends.", "type": "string" }, "id": { "description": "refresh-token family id, or a provider-session row id", "type": "string" }, "kind": { "description": "Kind names the id space: \"enforcer\" for a refresh-token family, otherwise\nthe provider that owns the session (\"privy\").", "type": "string", "example": "enforcer" }, "last_used_at": { "type": "string" }, "user_agent": { "type": "string" } } }, "enforcer-v3_internal_usecase_accounts.ProfileInput": { "type": "object", "properties": { "first_name": { "type": "string" }, "is_discoverable": { "description": "IsDiscoverable controls whether this account appears to other members in\ncontact discovery (/contacts/suggestions, /contacts/lookup, /contacts/\nresolve). It had no writer anywhere in the API: the column was stamped\nonce at account creation from the tenant's allow_user_discovery and could\nnever be changed, so \"discovery is opt-out\" was only true on paper.\n\nSelf-service by design — it is the subject's own privacy setting, and this\nendpoint is already reachable by the owner (write on your own account is\nthe authz baseline). It cannot be used to become MORE visible than the\ntenant permits: the tenant-wide allow_user_discovery gate is checked\nindependently on every discovery read, so a false there hides everyone\nregardless of this flag.", "type": "boolean" }, "last_name": { "type": "string" }, "username": { "type": "string" } } }, "enforcer-v3_internal_usecase_apikeys.Created": { "type": "object", "properties": { "api_key": { "$ref": "#/definitions/enforcer-v3_internal_domain_apikey.APIKey" }, "key": { "description": "full plaintext — shown once, never again", "type": "string" } } }, "enforcer-v3_internal_usecase_auth.AuthConfigResult": { "type": "object", "properties": { "auth_provider": { "type": "string" }, "privy_app_id": { "type": "string" } } }, "enforcer-v3_internal_usecase_auth.EmailStatus": { "type": "object", "properties": { "exists": { "type": "boolean" }, "verified": { "type": "boolean" } } }, "enforcer-v3_internal_usecase_auth.LoginRequest": { "type": "object", "properties": { "email": { "type": "string" }, "message": { "description": "SIWE EIP-4361 message", "type": "string" }, "otp": { "type": "string" }, "phone": { "type": "string" }, "provider": { "$ref": "#/definitions/enforcer-v3_internal_domain_identity.ProviderType" }, "signature": { "description": "SIWE signature", "type": "string" }, "tenant_code": { "type": "string" }, "token": { "type": "string" } } }, "enforcer-v3_internal_usecase_auth.RegisterPrivyInput": { "type": "object", "properties": { "email": { "type": "string" }, "tenant_code": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "enforcer-v3_internal_usecase_auth.RegisterPrivyResult": { "type": "object", "properties": { "status": { "type": "string" }, "wallet_pregenerated": { "type": "boolean" } } }, "enforcer-v3_internal_usecase_auth.RequestOTPInput": { "type": "object", "properties": { "email": { "type": "string" }, "tenant_code": { "type": "string" } } }, "enforcer-v3_internal_usecase_auth.Result": { "type": "object", "properties": { "account": { "$ref": "#/definitions/enforcer-v3_internal_domain_account.Account" }, "expires_at": { "type": "string" }, "is_new_account": { "type": "boolean" }, "refresh_token": { "type": "string" }, "token": { "type": "string" } } }, "enforcer-v3_internal_usecase_auth.SessionInfo": { "type": "object", "properties": { "client_ip": { "type": "string" }, "created_at": { "description": "CreatedAt is when the SESSION started, not when its current token was\nminted. Rotation used to advance this, so a session refreshed every 15\nminutes always reported itself as 15 minutes old.", "type": "string" }, "current": { "description": "Current marks the session this request is being made from — the one the\ncaller must NOT revoke if they intend to stay signed in. Resolved from\nwhichever id space the caller is in: the access token's sid claim for an\nenforcer session, the provider's sid for a Privy one. Still false for\nevery session when the credential carries neither (API key, portal link).", "type": "boolean" }, "expires_at": { "description": "ExpiresAt is nil for a provider session. Privy owns that session's\nlifetime and never tells us when it ends; reporting a guess on a security\nsurface would be worse than reporting nothing.", "type": "string" }, "id": { "type": "string" }, "kind": { "description": "Kind names which id space this session lives in. \"enforcer\" is a\nrefresh-token family; \"privy\" is a session the PROVIDER owns, which a\nclient authenticating with a raw Privy bearer is the only kind it has.\nBefore 000092 those were invisible here, so the primary client's session\nlist was permanently empty — the endpoint existed and answered \"none\".", "type": "string", "example": "enforcer" }, "last_used_at": { "description": "LastUsedAt is the last refresh for an enforcer session, and the last time\nthe token was PRESENTED for a provider one (advanced by a throttled write,\nso it lags by up to one interval). Nil only for an enforcer session that\nhas never rotated.", "type": "string" }, "user_agent": { "type": "string" } } }, "enforcer-v3_internal_usecase_connections.CreateInput": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": {} }, "name": { "type": "string" }, "provider_id": { "type": "string" } } }, "enforcer-v3_internal_usecase_connections.UpdateInput": { "type": "object", "properties": { "config": { "description": "non-nil replaces the whole config", "type": "object", "additionalProperties": {} }, "is_active": { "type": "boolean" }, "name": { "type": "string" } } }, "enforcer-v3_internal_usecase_contacts.ImportFieldError": { "type": "object", "properties": { "account_id": { "type": "string" }, "error": { "type": "string" } } }, "enforcer-v3_internal_usecase_contacts.ImportResult": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_usecase_contacts.ImportFieldError" } }, "failed": { "type": "integer" }, "imported": { "type": "integer" }, "skipped": { "description": "already a contact", "type": "integer" } } }, "enforcer-v3_internal_usecase_contacts.SendDestination": { "type": "object", "properties": { "address": { "description": "Address is lower-cased. Every comparison against it must lower-case the\nother side; EVM addresses are case-insensitive and the checksum casing a\nwallet or QR code emits is not stable across sources.", "type": "string" }, "contact_id": { "type": "string" }, "contact_type": { "type": "string" }, "name": { "type": "string" } } }, "enforcer-v3_internal_usecase_directory.Record": { "type": "object", "properties": { "account_id": { "type": "string" }, "active": { "type": "boolean" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "kyc_verified": { "type": "boolean" }, "last_name": { "type": "string" }, "person_id": { "type": "string" }, "phone": { "description": "person's primary phone; filled only when persons is wired", "type": "string" }, "role": { "type": "string" }, "tenant_id": { "type": "string" }, "username": { "type": "string" }, "wallet_address": { "type": "string" } } }, "enforcer-v3_internal_usecase_emailtemplates.WriteInput": { "type": "object", "properties": { "body_template": { "type": "string" }, "format": { "type": "string" }, "subject": { "type": "string" }, "template_id": { "type": "string" }, "tenant_id": { "description": "TenantID targets a tenant override (admin only — a tenant_admin is always\npinned to their own tenant). Empty = the system default (admin only).", "type": "string" } } }, "enforcer-v3_internal_usecase_groups.CreateInput": { "type": "object", "properties": { "description": { "type": "string" }, "group_type_id": { "description": "GroupTypeID classifies the group (optional). Must be a GLOBAL type or\none from the caller's tenant.", "type": "string" }, "is_public": { "type": "boolean" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "enforcer-v3_internal_usecase_groups.UpdateInput": { "type": "object", "properties": { "description": { "type": "string" }, "group_type_id": { "description": "GroupTypeID: nil = unchanged, \"\" = clear, uuid = retag (same tenant rule\nas CreateInput).", "type": "string" }, "is_public": { "type": "boolean" }, "name": { "type": "string" } } }, "enforcer-v3_internal_usecase_grouptypes.CreateInput": { "type": "object", "properties": { "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "name": { "type": "string" }, "slug": { "type": "string" }, "tenant_id": { "description": "TenantID targets a tenant-scoped type (admin only — a tenant_admin is\nalways pinned to their own tenant). Empty = GLOBAL for an admin, the\ncaller's own tenant for a tenant_admin (mirrors email templates).", "type": "string" } } }, "enforcer-v3_internal_usecase_grouptypes.UpdateInput": { "type": "object", "properties": { "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "name": { "type": "string" } } }, "enforcer-v3_internal_usecase_person.AccountSummary": { "type": "object", "properties": { "account_id": { "type": "string" }, "active": { "type": "boolean" }, "joined_at": { "type": "string" }, "last_login": { "type": "string" }, "role": { "type": "string" }, "tenant_id": { "type": "string" }, "tenant_name": { "type": "string" }, "username": { "type": "string" } } }, "enforcer-v3_internal_usecase_person.AdminDetail": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_usecase_person.AccountSummary" } }, "person": { "$ref": "#/definitions/enforcer-v3_internal_domain_person.Person" } } }, "enforcer-v3_internal_usecase_person.LookupResult": { "type": "object", "properties": { "exists": { "type": "boolean" }, "person_id": { "type": "string" } } }, "enforcer-v3_internal_usecase_person.MergeResult": { "type": "object", "properties": { "accounts_repointed": { "type": "integer" }, "target": { "$ref": "#/definitions/enforcer-v3_internal_domain_person.Person" } } }, "enforcer-v3_internal_usecase_person.PersonSearchItem": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_usecase_person.AccountSummary" } }, "created_at": { "type": "string" }, "dob": { "type": "string" }, "email_verified": { "type": "boolean" }, "first_name": { "type": "string" }, "home_address_line1": { "type": "string" }, "home_address_line2": { "type": "string" }, "home_city": { "type": "string" }, "home_country": { "type": "string" }, "home_place_id": { "description": "Home address — canonical, owned here (cybrid KYC + report-builder read it).\nHomePlaceID references an enforcer-geo place; the rest is a denormalized\nsnapshot so /auth/me serves the address without a geo round-trip.", "type": "string" }, "home_postal_code": { "type": "string" }, "home_region": { "type": "string" }, "id": { "type": "string" }, "last_name": { "type": "string" }, "name": { "description": "deprecated display name; prefer first_name/last_name", "type": "string" }, "phone_verified": { "type": "boolean" }, "primary_email": { "type": "string" }, "primary_phone": { "type": "string" }, "profile_image_url": { "type": "string" }, "updated_at": { "type": "string" } } }, "enforcer-v3_internal_usecase_person.SplitResult": { "type": "object", "properties": { "account_id": { "type": "string" }, "new_person": { "$ref": "#/definitions/enforcer-v3_internal_domain_person.Person" } } }, "enforcer-v3_internal_usecase_person.UpdateResult": { "type": "object", "properties": { "email_changed": { "description": "verified flag was cleared; re-verify needed", "type": "boolean" }, "person": { "$ref": "#/definitions/enforcer-v3_internal_domain_person.Person" }, "phone_changed": { "type": "boolean" } } }, "enforcer-v3_internal_usecase_policies.CheckResource": { "type": "object", "properties": { "id": { "description": "ID identifies the resource for logging and for custom policies that key\non it. It is NOT resolved to a stored row.", "type": "string" }, "owner_id": { "description": "OwnerID is the owning account. Required for an owner-baseline check.", "type": "string" }, "tenant_id": { "description": "TenantID is the owning tenant. Required for any tenant-scoped grant —\nincluding every admin-managed type. Omit it and the check is judged\nagainst an empty tenant, not against the caller's.", "type": "string" }, "type": { "type": "string", "example": "document" } } }, "enforcer-v3_internal_usecase_policies.EvaluateInput": { "type": "object", "properties": { "action": { "type": "string", "example": "read" }, "contexts": { "description": "Contexts is a free-form payload the policy may key on (size-capped).", "type": "object" }, "policy_id": { "description": "PolicyID selects a stored policy; empty falls through to the built-in\nstatic policy (HTTP parity with the gRPC Authorize).", "type": "string" }, "resource": { "$ref": "#/definitions/enforcer-v3_internal_usecase_policies.CheckResource" }, "user_id": { "description": "SubjectAccountID (user_id) evaluates on behalf of another account — the\ncaller must be able to read it. Empty = evaluate as the caller.", "type": "string" } } }, "enforcer-v3_internal_usecase_policies.WriteInput": { "type": "object", "properties": { "active": { "description": "Active defaults to true on create; on update it is applied as given.", "type": "boolean" }, "description": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "tenant_id": { "description": "TenantID targets a tenant-scoped policy (admin may target any tenant; a\ntenant_admin is always pinned to their own). Empty = a global policy\n(admin only).", "type": "string" } } }, "enforcer-v3_internal_usecase_referral.ClaimResult": { "type": "object", "properties": { "referrer_account_id": { "type": "string" } } }, "enforcer-v3_internal_usecase_referral.PublicJoin": { "type": "object", "properties": { "code": { "type": "string" }, "tenant_id": { "description": "TenantID is present only when Valid. A pointer, not a bare uuid.UUID:\nthat zero-valued to \"00000000-0000-0000-0000-000000000000\" and shipped it\non every invalid-code lookup, so an unauthenticated visitor pasting a\ntypo'd share link got back a syntactically valid tenant id. A client that\nreads tenant_id before checking valid would carry the nil UUID into a\njoin. omitempty on a [16]byte array does nothing, so the field has to be\nnilable to be omitted at all.", "type": "string" }, "valid": { "type": "boolean" } } }, "enforcer-v3_internal_usecase_ssoconnections.CreateInput": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": {} }, "name": { "type": "string" }, "provider_type": { "description": "\"oidc\" | \"saml\"", "type": "string" }, "slug": { "type": "string" } } }, "enforcer-v3_internal_usecase_ssoconnections.UpdateInput": { "type": "object", "properties": { "config": { "description": "non-nil replaces the config; omitted secrets are carried over", "type": "object", "additionalProperties": {} }, "is_active": { "type": "boolean" }, "name": { "type": "string" } } }, "enforcer-v3_internal_usecase_telemetry.RecordInput": { "type": "object", "properties": { "context": { "type": "object", "additionalProperties": { "type": "string" } }, "event": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "string" } } }, "enforcer-v3_internal_usecase_tenants.AuthProviderInput": { "type": "object", "properties": { "privy_app_id": { "description": "required when provider=privy", "type": "string" }, "provider": { "description": "\"native\" | \"privy\" | \"enterprise\"", "type": "string" } } }, "enforcer-v3_internal_usecase_tenants.CreateInput": { "type": "object", "properties": { "auth_provider": { "type": "string" }, "description": { "type": "string" }, "generate_code": { "type": "boolean" }, "name": { "type": "string" }, "privy_app_id": { "type": "string" }, "self_join_policy": { "type": "string" }, "wallet_provider": { "type": "string" } } }, "enforcer-v3_internal_usecase_tenants.ModulesInput": { "type": "object", "properties": { "modules": { "type": "array", "items": { "type": "string" } } } }, "enforcer-v3_internal_usecase_tenants.UpdateInput": { "type": "object", "properties": { "account_abstraction": { "type": "boolean" }, "app_url": { "type": "string" }, "auth_provider": { "type": "string" }, "banner_url": { "type": "string" }, "description": { "type": "string" }, "logo_url": { "type": "string" }, "metered_sends_enabled": { "type": "boolean" }, "name": { "type": "string" }, "payment_link_url": { "type": "string" }, "privy_app_id": { "type": "string" }, "self_join_policy": { "type": "string" }, "status": { "type": "string" }, "thumbnail_url": { "type": "string" }, "wallet_provider": { "type": "string" }, "web3_enabled": { "description": "Web3Enabled / MeteredSendsEnabled are the two web3 gates. They are validated\nas a PAIR against their effective values, so turning web3 off while metering\nis already on is refused just like turning metering on while web3 is off —\nthe same illegal state reached from either direction.", "type": "boolean" } } }, "enforcer-v3_internal_usecase_terms.Status": { "type": "object", "properties": { "has_mandatory_pending": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_usecase_terms.StatusItem" } } } }, "enforcer-v3_internal_usecase_terms.StatusItem": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "accepted_at": { "type": "string" }, "terms": { "$ref": "#/definitions/enforcer-v3_internal_domain_terms.Terms" } } }, "enforcer-v3_internal_usecase_verifications.GroupChallengeInput": { "type": "object", "properties": { "action": { "type": "string" }, "meta": { "type": "object", "additionalProperties": {} }, "provider": { "type": "string" } } }, "enforcer-v3_internal_usecase_verifications.GroupChallengeResult": { "type": "object", "properties": { "expires_at": { "type": "string" }, "group_added": { "type": "string" }, "sensitive_data": { "type": "object", "additionalProperties": {} }, "session_id": { "type": "string" }, "status": { "type": "string" } } }, "internal_delivery_http_handler.AcceptInviteRequest": { "type": "object", "properties": { "token": { "type": "string" } } }, "internal_delivery_http_handler.AccountListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.AccountView" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.AccountPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.AccountView" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.AccountResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.AccountView" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.AccountSearchResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.AccountView" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "scoped_to_tenant": { "type": "string", "format": "uuid" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.AccountView": { "type": "object", "properties": { "active": { "type": "boolean" }, "authenticated_at": { "type": "string" }, "created_at": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "first_name": { "type": "string" }, "id": { "type": "string" }, "invited_by": { "type": "string" }, "is_discoverable": { "type": "boolean" }, "last_active_at": { "type": "string" }, "last_login_at": { "type": "string" }, "last_name": { "type": "string" }, "person": { "$ref": "#/definitions/internal_delivery_http_handler.PersonView" }, "person_id": { "type": "string" }, "privy_user_id": { "type": "string" }, "profile_completed": { "type": "boolean" }, "role": { "$ref": "#/definitions/enforcer-v3_internal_domain_role.Role" }, "role_id": { "type": "string" }, "tenant": { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.Tenant" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" }, "username": { "type": "string" }, "verification_status": { "description": "VerificationStatus is the KYC rollup bucket — verified | pending | failed\n| none — decorated onto list rows, absent on payloads that do not resolve\nit. NOT the same thing as ProfileCompleted, which is an admin-set\nprovisioner flag and says nothing about identity.", "type": "string" }, "wallet_address": { "type": "string" } } }, "internal_delivery_http_handler.AckAllFulfillmentsRequest": { "type": "object", "properties": { "contact": { "description": "scope to one counterparty (its account id)", "type": "string" }, "created_after": { "description": "RFC3339 window floor (match the badge read's floor)", "type": "string" }, "direction": { "description": "\"sent\" | \"received\" | \"\" (all)", "type": "string" }, "self_payments": { "description": "include (default) | exclude | only", "type": "string" }, "type": { "description": "\"seen\" (default) | \"paid\"", "type": "string" } } }, "internal_delivery_http_handler.AckFulfillmentRequest": { "type": "object", "properties": { "type": { "description": "\"seen\" | \"paid\"", "type": "string" } } }, "internal_delivery_http_handler.AdminFulfillmentListResponse": { "type": "object", "properties": { "fulfillments": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.Fulfillment" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "tenant_id": { "type": "string" }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.AdminFulfillmentTimeseriesResponse": { "type": "object", "properties": { "bucket": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.TimeseriesBucket" } }, "success": { "type": "boolean", "example": true }, "tenant_id": { "type": "string" }, "user_id": { "type": "string" } } }, "internal_delivery_http_handler.AdminIdentityData": { "type": "object", "properties": { "account_email": { "type": "string" }, "account_email_verified": { "type": "boolean" }, "account_id": { "type": "string" }, "account_phone": { "description": "AccountPhone is persons.primary_phone — accounts carry no phone column.", "type": "string" }, "account_phone_verified": { "type": "boolean" }, "auth_provider": { "description": "AuthProvider is the tenant's effective provider and the context for every\nnull below — a native or enterprise tenant has no Privy side at all.", "type": "string", "example": "privy" }, "email_matches_account": { "description": "EmailMatchesAccount is the field to read first. A Privy-linked address that\nhas drifted from accounts.email sends every login code to an inbox the user\nno longer reads, and nothing else in the database exposes it. null — never\nfalse — when either side is blank: \"Privy holds no email\" is a different\nproblem from \"the emails disagree\", and both values are in this body, so a\nnull always explains itself.", "type": "boolean" }, "last_login_at": { "description": "LastLoginAt is EMPTY for every Privy-token user by construction, not by\naccident. It ships anyway: seeing the blank next to a healthy Privy posture\nis what stops the next reader taking it for \"never logged in\".", "type": "string" }, "passkey_mfa": { "description": "PasskeyMfa is the same live posture GET /accounts/{id}/passkey-mfa serves,\nfolded in so a lockout ticket costs one request rather than three.", "allOf": [ { "$ref": "#/definitions/internal_delivery_http_handler.PasskeyMfaStatusData" } ] }, "phone_matches_account": { "description": "PhoneMatchesAccount is the same comparison for the number, both sides\ncanonicalized so formatting is never reported as drift.", "type": "boolean" }, "privy": { "description": "Privy is null for an account with no Privy user.", "allOf": [ { "$ref": "#/definitions/internal_delivery_http_handler.AdminIdentityPrivyData" } ] }, "privy_user_id": { "type": "string", "example": "did:privy:clx0…" }, "tenant_id": { "type": "string" } } }, "internal_delivery_http_handler.AdminIdentityPrivyData": { "type": "object", "properties": { "email": { "type": "string", "example": "velvia@example.com" }, "phone": { "type": "string", "example": "+15108675310" } } }, "internal_delivery_http_handler.AdminIdentityResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.AdminIdentityData" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.AdminSessionListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_usecase_accounts.AdminSessionInfo" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.AdoptMultisigWalletRequest": { "type": "object", "properties": { "privy_wallet_id": { "type": "string" } } }, "internal_delivery_http_handler.AdoptMultisigWalletResponse": { "type": "object", "properties": { "address": { "type": "string" }, "owner_quorum_id": { "type": "string" }, "success": { "type": "boolean" } } }, "internal_delivery_http_handler.ApiKeyCreatedResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_apikeys.Created" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ApiKeyPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_apikey.APIKey" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.AuditEventPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_audit.Event" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.AuthAttemptListResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_authattempt.Event" } }, "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "tenant_id": { "description": "TenantID is the tenant actually read, which for a tenant-scoped caller is\nalways their own regardless of what they asked for.", "type": "string" }, "total": { "type": "integer", "example": 3 } } }, "internal_delivery_http_handler.AuthAttemptRequest": { "type": "object", "properties": { "context": { "type": "object", "additionalProperties": { "type": "string" } }, "email": { "description": "Email is the address the attempt was made with. Stored hashed and masked,\nnever in the clear.", "type": "string", "example": "v...@msn.com" }, "event": { "description": "Event must be one of the closed set: otp_requested, otp_send_failed,\notp_verify_failed, login_failed.", "type": "string", "example": "otp_verify_failed" }, "message": { "type": "string" }, "tenant_code": { "description": "TenantCode names the tenant — the same handle the client already passes to\nGET /auth/config, since a pre-auth caller has no other.", "type": "string", "example": "MEGPRIME" } } }, "internal_delivery_http_handler.AuthConfigResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_auth.AuthConfigResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.AuthResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_auth.Result" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.AuthzCheckResponse": { "type": "object", "properties": { "allow": { "type": "boolean" }, "policy_id": { "type": "string" }, "reason": { "type": "string" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.BatchRequest": { "type": "object", "properties": { "account_ids": { "type": "array", "items": { "type": "string" } } } }, "internal_delivery_http_handler.BulkAckFulfillmentsRequest": { "type": "object", "properties": { "acknowledged": { "description": "Acknowledged defaults to true (POST /ack means \"mark\"); pass false to\nclear. Idempotent set/clear, not a toggle.", "type": "boolean" }, "ids": { "type": "array", "items": { "type": "string" } }, "type": { "description": "\"seen\" (default) | \"paid\"", "type": "string" } } }, "internal_delivery_http_handler.BulkAckFulfillmentsResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.BulkAckResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.BulkAckResult": { "type": "object", "properties": { "skipped": { "type": "integer" }, "updated": { "type": "integer" } } }, "internal_delivery_http_handler.BulkResultResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.BulkSummary" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.BulkSummary": { "type": "object", "properties": { "failed": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.bulkItem" } }, "succeeded": { "type": "integer" } } }, "internal_delivery_http_handler.CapabilityListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_connection.Capability" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ChallengeResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_verifications.GroupChallengeResult" }, "success": { "type": "boolean" } } }, "internal_delivery_http_handler.ClaimCodeRequest": { "type": "object", "properties": { "code": { "type": "string" } } }, "internal_delivery_http_handler.ClientEventListResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_telemetry.ClientEvent" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.ConnectionPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_connection.TenantConnection" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.ConnectionResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_connection.TenantConnection" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ContactImportResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_contacts.ImportResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ContactPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_contact.Contact" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.ContactResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_contact.Contact" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ContactUnseenCountsData": { "type": "object", "properties": { "counts": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.ContactUnseenCount" } } } }, "internal_delivery_http_handler.ContactUnseenCountsResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.ContactUnseenCountsData" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.CreateContactRequest": { "type": "object", "properties": { "contact_account_id": { "type": "string" }, "custom_avatar_url": { "description": "CustomAvatarURL is this owner's private picture override for the contact —\na CDN URL previously returned by an enforcer-files image upload. Set on a\nLINKED contact it shadows that person's own profile picture, for this owner\nonly; on a custom contact it is the only picture available. Must be https\nand, when the deployment configures an allowlist, on an approved CDN host.", "type": "string" }, "custom_email": { "type": "string" }, "custom_first_name": { "type": "string" }, "custom_last_name": { "type": "string" }, "custom_phone_number": { "type": "string" }, "custom_wallet_address": { "description": "CustomWalletAddress is the pay-to wallet for a custom (off-platform)\ncontact — the QR-scan flow's payload. Previously ABSENT from this struct:\nthe client sent it, the server silently dropped it, and wallet-only\ncontacts landed unpayable and un-dedupable.", "type": "string" }, "description": { "type": "string" }, "name": { "type": "string" } } }, "internal_delivery_http_handler.CreateFulfillmentRequest": { "type": "object", "properties": { "chain_id": { "type": "integer" }, "deadline": { "description": "RFC3339", "type": "string" }, "expected_plan_hash": { "type": "string" }, "idempotency_key": { "description": "IdempotencyKey de-duplicates this create. Optional, but strongly advised\nfor any client that can retry: pass the same key and a second call returns\nthe ORIGINAL fulfillment (200-shaped, same id) instead of minting a second\npayment. Unique per tenant, 8..255 chars, and durable for the row's whole\nlife — a retry after the original settled still resolves to it.", "type": "string" }, "max_fee_bps": { "type": "integer" }, "memo": { "type": "string" }, "notional_uoa": { "type": "string" }, "receiver_user_id": { "type": "string" }, "receiver_wallet": { "type": "string" }, "reference": { "type": "string" }, "request_token": { "type": "string" }, "sender_user_id": { "description": "SenderUserID addresses the payer by account id — used by the \"request\" flow\nwhen the contact has no on-chain wallet on file. Optional: when unset, the\nsender defaults to the caller (the \"send\" flow). Mutually optional with\nsender_wallet.", "type": "string" }, "sender_wallet": { "type": "string" } } }, "internal_delivery_http_handler.CreateInviteRequest": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string" } } }, "internal_delivery_http_handler.CreateKeyRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "internal_delivery_http_handler.CreateRoleRequest": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "permissions": { "$ref": "#/definitions/internal_delivery_http_handler.PermissionsBody" }, "slug": { "type": "string" } } }, "internal_delivery_http_handler.CreateTermsRequest": { "type": "object", "properties": { "content": { "type": "string" }, "effective_at": { "type": "string" }, "expires_at": { "type": "string" }, "is_mandatory": { "type": "boolean" }, "summary": { "type": "string" }, "tenant_id": { "description": "admin only; tenant admins are forced to their own tenant", "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "version": { "type": "string" } } }, "internal_delivery_http_handler.CreateWalletRequest": { "type": "object", "properties": { "chain_type": { "description": "ChainType defaults to \"ethereum\".", "type": "string" }, "description": { "description": "Description is free text stored in the wallet's metadata.", "type": "string" }, "label": { "description": "Label is the wallet's display name, mirrored to the provider. Max 100.", "type": "string" }, "make_primary": { "description": "MakePrimary promotes the new wallet immediately, re-pointing the address\nother users pay to.", "type": "boolean" } } }, "internal_delivery_http_handler.CredentialListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_passkey.Credential" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.CredentialResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_passkey.Credential" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.DLQEntryListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_maildlq.Entry" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.DeletedCount": { "type": "object", "properties": { "deleted": { "type": "integer" } } }, "internal_delivery_http_handler.DeletedResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.DeletedCount" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.DeviceListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_device.PersonDevice" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.DeviceProviderListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_device.DeviceType" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.DeviceResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_device.PersonDevice" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.DirectoryRecordListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_usecase_directory.Record" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.DirectoryRecordResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_directory.Record" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.DiscoveryPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.DiscoveryView" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.DiscoveryResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.DiscoveryView" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.DiscoveryView": { "type": "object", "properties": { "email_verified": { "description": "Verification badges — the flags, never the underlying identifiers.", "type": "boolean" }, "first_name": { "type": "string" }, "id": { "type": "string" }, "last_name": { "type": "string" }, "name": { "description": "Name is the person's display name when set, which is what the picker\nshows in preference to the account's first/last pair.", "type": "string" }, "phone_verified": { "type": "boolean" }, "profile_image_url": { "type": "string" }, "tenant_id": { "type": "string" }, "username": { "type": "string" }, "wallet_address": { "description": "WalletAddress is the primary address. Kept because discovery feeds the\nsend-destination picker; the VALUE is already public on-chain, unlike\neverything dropped above.", "type": "string" } } }, "internal_delivery_http_handler.EmailCheckRequest": { "type": "object", "properties": { "code": { "type": "string" }, "email": { "type": "string" } } }, "internal_delivery_http_handler.EmailStartRequest": { "type": "object", "properties": { "email": { "type": "string" } } }, "internal_delivery_http_handler.EmailStatusResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_auth.EmailStatus" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "bad_request" }, "message": { "type": "string" } } }, "internal_delivery_http_handler.FulfillmentPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.Fulfillment" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.FulfillmentResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.Fulfillment" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.FulfillmentStatusResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.StatusProjection" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.FulfillmentSummaryResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_fulfillment.Summary" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.GroupPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_group.Group" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.GroupResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_group.Group" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.GroupTypePageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_grouptype.GroupType" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.GroupTypeResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_grouptype.GroupType" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.HealthStatusResponse": { "type": "object", "properties": { "checks": { "type": "object", "additionalProperties": { "type": "string" } }, "status": { "type": "string", "example": "ok" }, "time": { "type": "string" }, "version": { "description": "Version is the git revision this binary was built from, or \"unknown\" when\nthe build carries no stamp. Its ABSENCE is meaningful too: a response with\nno version field is an image predating this endpoint, which is usually the\nanswer a deploy check wants.", "type": "string", "example": "b0026a19c3f2" } } }, "internal_delivery_http_handler.IDsRequest": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } } } }, "internal_delivery_http_handler.InvitePageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_invite.Invite" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.InviteResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_invite.Invite" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.InviteSummaryResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_invite.Summary" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.JoinTenantRequest": { "type": "object", "properties": { "tenant_code": { "type": "string" } } }, "internal_delivery_http_handler.LinkContactRequest": { "type": "object", "properties": { "target_account_id": { "type": "string" } } }, "internal_delivery_http_handler.LogoutRequest": { "type": "object", "properties": { "refresh_token": { "type": "string" } } }, "internal_delivery_http_handler.MeData": { "type": "object", "properties": { "account_id": { "type": "string" }, "active": { "type": "boolean" }, "authenticated_at": { "description": "authenticated_at / last_login_at update only on a fresh Login (not on token\nrefresh); last_active_at is the warm-path freshness signal (throttled).", "type": "string" }, "created_at": { "type": "string" }, "groups": { "description": "Groups are the authz groups the caller belongs to, resolved to {id, slug,\nname} so clients can gate on slug + display a label without a separate\nlookup. No omitempty: always an array (NewMeData seeds []), so a groupless\naccount serializes as [] rather than null/absent.", "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.MeGroup" } }, "is_discoverable": { "type": "boolean" }, "kyc_verified": { "description": "No omitempty: a bool false must serialize so clients can distinguish\n\"not KYC-verified\" from \"field absent / older server\".", "type": "boolean" }, "last_active_at": { "type": "string" }, "last_login_at": { "type": "string" }, "passkey_mfa_verified_at": { "description": "PasskeyMfaVerifiedAt is the server-verified passkey MFA completeness\nstamp (POST /auth/me/passkey/verify). Clients gate onboarding on this,\nnot on Privy's eventually-consistent client SDK arrays. NULL/absent =\nnever server-verified.", "type": "string" }, "person": { "description": "Canonical identity + auth context (nested; each carries its own id).", "allOf": [ { "$ref": "#/definitions/enforcer-v3_internal_domain_person.Person" } ] }, "privy_user_id": { "type": "string" }, "profile_completed": { "type": "boolean" }, "referral": { "description": "Referral is the caller's own affiliate/referral code (id + code), folded in\nso the client doesn't need a separate GET /referrals/my-code on hydration.\nBest-effort: omitted if the lookup/mint fails.", "allOf": [ { "$ref": "#/definitions/internal_delivery_http_handler.MeReferral" } ] }, "role": { "$ref": "#/definitions/enforcer-v3_internal_domain_role.Role" }, "tenant": { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.Tenant" }, "terms": { "description": "Terms posture — slim: one flat entry per current document (id + acceptance,\nno document body) plus the mandatory gate. Enough to drive the onboarding\ngate/badge; fetch full text from GET /terms/{id} or /auth/me/terms.\nBest-effort: omitted if the terms lookup fails.", "allOf": [ { "$ref": "#/definitions/internal_delivery_http_handler.MeTerms" } ] }, "updated_at": { "type": "string" }, "username": { "type": "string" }, "verifications": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_authz.VerificationRef" } }, "wallet_address": { "description": "WalletAddress is the account's PRIMARY wallet — the denormalized mirror of\naccount_wallets' primary row, which is what deposits, contact lookups and\nevery account-keyed read resolve to. Absent when the account holds none.\n\nDeliberately just the address, and deliberately taken from the account row so\n/auth/me stays a single query: this is the hydration path, and it is called on\nevery app open. The wallet's KIND and its signing posture are a different\nquestion with a different cost — GET /me/wallets lists all of them with kind\nand owner quorum, and GET /me/wallets/multisig reads the live posture from the\nprovider. A client that needs to know whether the primary is a co-signed 2-of-2\nmust ask one of those; this field only says which address is primary.", "type": "string" }, "wallet_send_migration_required": { "description": "WalletSendMigrationRequired is true when this account holds a smart wallet\non a send-enforced tenant (a tenant_connections row carries the flag) that\nhasn't yet had the mandatory app-key owner quorum attached. Set by the Me\nhandler (needs a connections lookup, so NewMeData can't compute it). The\nPWA reads it here to prompt the one-time, user-authorized owner-change.\nNo omitempty: a false must serialize so clients distinguish \"not required\"\nfrom \"older server\".", "type": "boolean" } } }, "internal_delivery_http_handler.MeGroup": { "type": "object", "properties": { "group_type_id": { "description": "GroupTypeID is the group's taxonomy, so a client can gate on \"my groups\nof type X\" without a second call. Omitted for an untyped group.\n\nA slug alone is already unambiguous WITHIN a tenant (uk_groups_tenant_slug\nis on (tenant_id, slug), not (tenant_id, group_type_id, slug)), so a\nconsumer that knows its slugs up front does not need this field — it is\nfor the caller that wants to enumerate one taxonomy it does not have a\nslug list for.", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "internal_delivery_http_handler.MeReferral": { "type": "object", "properties": { "code": { "type": "string" }, "id": { "type": "string" } } }, "internal_delivery_http_handler.MeResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.MeData" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.MeTerms": { "type": "object", "properties": { "has_mandatory_pending": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.MeTermsItem" } } } }, "internal_delivery_http_handler.MeTermsItem": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "accepted_at": { "type": "string" }, "id": { "type": "string" }, "is_mandatory": { "type": "boolean" }, "title": { "type": "string" }, "type": { "type": "string" }, "version": { "type": "string" } } }, "internal_delivery_http_handler.MemberRequest": { "type": "object", "properties": { "account_id": { "type": "string" } } }, "internal_delivery_http_handler.MessageResponse": { "type": "object", "properties": { "message": { "type": "string" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.MyAccountListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_usecase_person.AccountSummary" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.OAuthClientPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.OAuthClientSummary" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.OAuthClientSummary": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_id_issued_at": { "type": "string" }, "client_name": { "type": "string" }, "confidential": { "description": "Confidential separates the clients an admin minted, which can exchange\ntokens, from the ones that registered themselves and cannot.", "type": "boolean" }, "disabled": { "type": "boolean" }, "disabled_at": { "type": "string" }, "grant_types": { "type": "array", "items": { "type": "string" } }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_exchange_resource": { "type": "string" } } }, "internal_delivery_http_handler.OKResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.OtpRequestResponse": { "type": "object", "properties": { "dev_otp": { "type": "string" }, "message": { "type": "string" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PasskeyChallengeResponse": { "type": "object", "properties": { "handle": { "type": "string" }, "options": { "type": "object" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PasskeyLoginBeginRequest": { "type": "object", "properties": { "tenant_code": { "type": "string" } } }, "internal_delivery_http_handler.PasskeyLoginFinishRequest": { "type": "object", "properties": { "credential": { "type": "array", "items": { "type": "integer" } }, "handle": { "type": "string" } } }, "internal_delivery_http_handler.PasskeyMfaCredentialData": { "type": "object", "properties": { "authenticator_name": { "type": "string", "example": "Google Password Manager" }, "created_with_browser": { "type": "string" }, "created_with_device": { "type": "string" }, "created_with_os": { "type": "string" }, "credential_id": { "type": "string" }, "enrolled_in_mfa": { "type": "boolean" }, "first_verified_at": { "type": "string" }, "latest_verified_at": { "type": "string" } } }, "internal_delivery_http_handler.PasskeyMfaData": { "type": "object", "properties": { "credentials": { "type": "integer", "example": 1 }, "factor_advertised": { "type": "boolean", "example": true }, "methods": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "example": "enrolled" }, "verified_at": { "type": "string" } } }, "internal_delivery_http_handler.PasskeyMfaStatusData": { "type": "object", "properties": { "account_id": { "type": "string" }, "credentials": { "type": "integer", "example": 1 }, "factor_advertised": { "type": "boolean", "example": true }, "methods": { "type": "array", "items": { "type": "string" } }, "needs_stamp": { "description": "NeedsStamp: enrolled on Privy, never stamped here — safe to backfill.", "type": "boolean", "example": false }, "passkeys": { "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.PasskeyMfaCredentialData" } }, "privy_user_id": { "type": "string" }, "stamp_diverged": { "description": "StampDiverged: stamped, but Privy no longer reports a backed enrollment.", "type": "boolean", "example": false }, "state": { "type": "string", "example": "enrolled" }, "tenant_id": { "type": "string" }, "verified_at": { "type": "string" } } }, "internal_delivery_http_handler.PasskeyMfaStatusResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.PasskeyMfaStatusData" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PasskeyMfaVerifyResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.PasskeyMfaData" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PermissionsBody": { "type": "object", "properties": { "admin_managed": { "type": "boolean" }, "cross_tenant": { "type": "boolean" }, "tenant_manage": { "type": "boolean" }, "tenant_read": { "type": "boolean" }, "tenant_write": { "type": "boolean" } } }, "internal_delivery_http_handler.PersonAdminDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_person.AdminDetail" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PersonCascadeResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_person.CascadeResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PersonLookupResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_person.LookupResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PersonMergeResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_person.MergeResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PersonPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_usecase_person.PersonSearchItem" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.PersonResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_person.Person" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PersonSplitResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_person.SplitResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PersonUpdateResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_person.UpdateResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PersonVerificationsPage": { "type": "object", "properties": { "filtered": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_personverification.PersonVerification" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.PersonVerificationsPageResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.PersonVerificationsPage" }, "success": { "type": "boolean" } } }, "internal_delivery_http_handler.PersonView": { "type": "object", "properties": { "first_name": { "type": "string" }, "id": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "phone_verified": { "type": "boolean" }, "primary_phone": { "description": "Phone lives on the person (persons.primary_phone) — surfaced here so\nadmin lists can show phone + its verification without a second read.", "type": "string" }, "profile_image_url": { "type": "string" } } }, "internal_delivery_http_handler.PhoneCaptureData": { "type": "object", "properties": { "phone": { "type": "string", "example": "+15108675310" }, "phone_verified": { "type": "boolean", "example": true }, "privy_checked": { "type": "boolean", "example": true }, "sms_mfa_enrolled": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PhoneCaptureRequest": { "type": "object", "properties": { "phone": { "type": "string", "example": "+15108675310" } } }, "internal_delivery_http_handler.PhoneCaptureResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.PhoneCaptureData" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PhoneCheckRequest": { "type": "object", "properties": { "code": { "type": "string" }, "phone": { "type": "string" } } }, "internal_delivery_http_handler.PhoneRiskData": { "type": "object", "properties": { "line_type": { "type": "string" }, "number_blocked": { "type": "boolean" }, "pumping_risk_category": { "type": "string" }, "pumping_score": { "type": "integer" }, "risky": { "type": "boolean" }, "valid": { "type": "boolean" } } }, "internal_delivery_http_handler.PhoneRiskResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.PhoneRiskData" }, "success": { "type": "boolean" } } }, "internal_delivery_http_handler.PhoneStartRequest": { "type": "object", "properties": { "phone": { "type": "string" } } }, "internal_delivery_http_handler.PolicyPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_policy.Policy" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.PolicyResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_policy.Policy" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.PrivyRegisterResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_auth.RegisterPrivyResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ProviderListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_connection.Provider" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ReasonRequest": { "type": "object", "properties": { "reason": { "type": "string" } } }, "internal_delivery_http_handler.RecallFulfillmentRequest": { "type": "object", "properties": { "reason": { "type": "string" } } }, "internal_delivery_http_handler.ReferralClaimResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_referral.ClaimResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ReferralCodeResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_referral.Code" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ReferralInvitedResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_referral.InvitedUser" } }, "kyc_verified": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.ReferralLeaderboardResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_referral.LeaderRow" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.ReferralPublicJoinResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_referral.PublicJoin" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.ReferralStatsResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_referral.Stats" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.RefreshRequest": { "type": "object", "properties": { "refresh_token": { "type": "string" } } }, "internal_delivery_http_handler.RegisterDeviceRequest": { "type": "object", "properties": { "app_identifier": { "type": "string" }, "app_version": { "type": "string" }, "device_id": { "type": "string" }, "device_name": { "type": "string" }, "key_algorithm": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "os_name": { "type": "string" }, "os_version": { "type": "string" }, "provider": { "type": "string" }, "public_key": { "type": "string" }, "push_token": { "type": "string" } } }, "internal_delivery_http_handler.RegisterFinishReq": { "type": "object", "properties": { "credential": { "description": "raw WebAuthn attestation response", "type": "array", "items": { "type": "integer" } }, "friendly_name": { "type": "string" }, "handle": { "type": "string" } } }, "internal_delivery_http_handler.RegisterResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.RegisterResult" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.RegisterResult": { "type": "object", "properties": { "account": { "$ref": "#/definitions/enforcer-v3_internal_domain_account.Account" }, "is_new_account": { "type": "boolean" } } }, "internal_delivery_http_handler.RequestSMSRequest": { "type": "object", "properties": { "phone": { "type": "string" }, "tenant_code": { "type": "string" } } }, "internal_delivery_http_handler.RevokedSessionsResponse": { "type": "object", "properties": { "revoked": { "type": "integer" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.RolePageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_role.Role" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.RoleResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_role.Role" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.SSOConnectionPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_sso.Connection" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.SSOConnectionResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_sso.Connection" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.SSOExchangeRequest": { "type": "object", "properties": { "code": { "type": "string" } } }, "internal_delivery_http_handler.SelfServeTenantRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "internal_delivery_http_handler.SendDestinationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_usecase_contacts.SendDestination" } }, "success": { "type": "boolean" } } }, "internal_delivery_http_handler.SessionListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_usecase_auth.SessionInfo" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.SessionsPage": { "type": "object", "properties": { "filtered": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_verification.Session" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.SessionsPageResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.SessionsPage" }, "success": { "type": "boolean" } } }, "internal_delivery_http_handler.SessionsResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_verification.Session" } }, "success": { "type": "boolean" } } }, "internal_delivery_http_handler.SetActiveRequest": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "internal_delivery_http_handler.SetActiveTermsRequest": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "internal_delivery_http_handler.SetContactFavoriteRequest": { "type": "object", "properties": { "rank": { "type": "integer" } } }, "internal_delivery_http_handler.SetProfileCompletedRequest": { "type": "object", "properties": { "profile_completed": { "type": "boolean" } } }, "internal_delivery_http_handler.SetRoleRequest": { "type": "object", "properties": { "role": { "description": "role slug", "type": "string" } } }, "internal_delivery_http_handler.SiweNonceRequest": { "type": "object", "properties": { "tenant_code": { "type": "string" }, "wallet_address": { "type": "string" } } }, "internal_delivery_http_handler.SiweNonceResponse": { "type": "object", "properties": { "nonce": { "type": "string" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.StringListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "type": "string" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.SubmitFulfillmentRequest": { "type": "object", "properties": { "tx_hash": { "type": "string" } } }, "internal_delivery_http_handler.SupportContactRequest": { "type": "object", "properties": { "body": { "type": "string", "example": "I need help with my account." }, "source": { "description": "Source is an OPTIONAL stamp for program-filed tickets: \"automated\" marks\nthe ticket as filed by code (the PWA's Plaid auto-ticket), so the support\nqueue can hide it server-side (GET /tickets?source=support_contact)\ninstead of guessing from the subject. Omitted = support_contact (a\nperson). Any other value is a 400.", "type": "string", "enum": [ "automated" ], "example": "automated" }, "subject": { "type": "string", "example": "MegPrime Support Request" } } }, "internal_delivery_http_handler.SupportContactResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "ticket_id": { "type": "string", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } }, "internal_delivery_http_handler.SwitchTenantRequest": { "type": "object", "properties": { "tenant_id": { "type": "string" } } }, "internal_delivery_http_handler.TelemetryRecordedResponse": { "type": "object", "properties": { "recorded": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TemplatePageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_emailtemplate.Template" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.TemplateResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_emailtemplate.Template" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TenantCode": { "type": "object", "properties": { "code": { "type": "string" }, "id": { "type": "string" } } }, "internal_delivery_http_handler.TenantCodeResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.TenantCode" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TenantPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.Tenant" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.TenantResolveResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.Tenant" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TenantResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.Tenant" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TenantSummaryResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_tenant.Summary" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TermsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_terms.Terms" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.TermsResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_terms.Terms" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TermsStatusResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_usecase_terms.Status" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TicketAttachmentURLResponse": { "type": "object", "properties": { "expires_at": { "type": "string", "example": "2026-08-10T12:34:56Z" }, "success": { "type": "boolean", "example": true }, "url": { "type": "string" } } }, "internal_delivery_http_handler.TicketCreateRequest": { "type": "object", "properties": { "body": { "type": "string", "example": "My payment to ACME was declined twice." }, "priority": { "type": "string", "example": "normal" }, "requester_account_id": { "type": "string" }, "subject": { "type": "string", "example": "Card payment failed" } } }, "internal_delivery_http_handler.TicketMessagePageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_ticket.Message" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.TicketMessageRequest": { "type": "object", "properties": { "body": { "type": "string", "example": "Thanks — we're looking into it." }, "file_ids": { "type": "array", "items": { "type": "string" } }, "internal": { "type": "boolean", "example": false } } }, "internal_delivery_http_handler.TicketMessageResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_ticket.Message" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TicketPageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_ticket.Ticket" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean", "example": true }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.TicketResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/enforcer-v3_internal_domain_ticket.Ticket" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TicketSummary": { "type": "object", "properties": { "by_status": { "type": "object", "additionalProperties": { "type": "integer" } }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.TicketSummaryResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.TicketSummary" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.TicketUpdateRequest": { "type": "object", "properties": { "assignee_account_id": { "type": "string" }, "clear_assignee": { "type": "boolean" }, "priority": { "type": "string", "example": "high" }, "status": { "type": "string", "example": "resolved" } } }, "internal_delivery_http_handler.TurnstileVerifyRequest": { "type": "object", "properties": { "token": { "type": "string" } } }, "internal_delivery_http_handler.TurnstileVerifyResponse": { "type": "object", "properties": { "action": { "type": "string" }, "error_codes": { "type": "array", "items": { "type": "string" } }, "hostname": { "type": "string" }, "success": { "description": "deprecated: token validity, NOT request success — read Valid", "type": "boolean" }, "valid": { "type": "boolean" } } }, "internal_delivery_http_handler.UpdateContactRequest": { "type": "object", "properties": { "active": { "type": "boolean" }, "blacklisted": { "type": "boolean" }, "custom_avatar_url": { "description": "CustomAvatarURL replaces the picture override. Send \"\" to CLEAR it, which\nfalls a linked contact back to that person's own profile picture; omit the\nfield to leave it unchanged.", "type": "string" }, "custom_email": { "type": "string" }, "custom_first_name": { "type": "string" }, "custom_last_name": { "type": "string" }, "custom_phone_number": { "type": "string" }, "custom_wallet_address": { "description": "CustomWalletAddress registers the pay-to wallet on a CUSTOM contact — the\nact that makes the contact payable, since send destinations derive from the\naddress book. Send \"\" to CLEAR it, which revokes that permission; omit to\nleave unchanged. Rejected (400) on a linked contact, whose address is their\nown account's active wallet.", "type": "string" }, "description": { "type": "string" }, "name": { "type": "string" } } }, "internal_delivery_http_handler.UpdateDeviceRequest": { "type": "object", "properties": { "device_name": { "type": "string" }, "status": { "type": "string" } } }, "internal_delivery_http_handler.UpdatePersonRequest": { "type": "object", "properties": { "dob": { "description": "YYYY-MM-DD", "type": "string" }, "first_name": { "type": "string" }, "home_address_line1": { "type": "string" }, "home_address_line2": { "type": "string" }, "home_city": { "type": "string" }, "home_country": { "type": "string" }, "home_place_id": { "type": "string" }, "home_postal_code": { "type": "string" }, "home_region": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "primary_email": { "type": "string" }, "primary_phone": { "type": "string" }, "profile_image_url": { "type": "string" }, "username": { "description": "account-scoped; applied to the caller's current account", "type": "string" } } }, "internal_delivery_http_handler.UpdateRoleRequest": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "permissions": { "$ref": "#/definitions/internal_delivery_http_handler.PermissionsBody" } } }, "internal_delivery_http_handler.UpdateWalletRequest": { "type": "object", "properties": { "description": { "type": "string" }, "label": { "type": "string" } } }, "internal_delivery_http_handler.WalletAuditListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/enforcer-v3_internal_domain_walletaudit.Finding" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "success": { "type": "boolean" }, "total": { "type": "integer" } } }, "internal_delivery_http_handler.WalletListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.WalletView" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.WalletMultisigListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/internal_delivery_http_handler.WalletMultisigView" } }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.WalletMultisigView": { "type": "object", "properties": { "address": { "type": "string" }, "authorization_keys": { "type": "integer" }, "kind": { "description": "Kind is \"smart\" or \"embedded\".", "type": "string" }, "needs_owner_migration": { "description": "NeedsOwnerMigration is true when the one-time user-authorized owner change\nstill has to happen for this wallet.", "type": "boolean" }, "owner_quorum_id": { "type": "string" }, "requires_both_signatures": { "description": "RequiresBothSignatures is the field a UI must render \"protected\" from, and\nrequires_server_cosign is NOT a substitute for it. The latter is also true\nof an app-only quorum (the server signs alone — full custody) and of a\nquorum whose app keys already meet the threshold, both of which would\ndisplay as \"we co-sign your transactions\" while meaning the opposite. This\nfield is true only when neither the user alone nor the server alone can\nsign.", "type": "boolean" }, "requires_server_cosign": { "description": "RequiresServerCosign is the question that matters: true means the user's\nsession alone can no longer sign, so the server must co-sign. It needs BOTH\nan app key in the quorum AND threshold \u003e= 2 — an app key at threshold 1 lets\nthe server sign but leaves the user able to sign alone too, which is\ncapability without enforcement.", "type": "boolean" }, "resolved": { "description": "Resolved is false when the posture could not be read from the provider; the\nfields above are then unknown rather than \"not required\".", "type": "boolean" }, "signer_address": { "type": "string" }, "signer_wallet_id": { "description": "SignerWalletID is the Privy wallet id whose owner quorum governs this\nwallet — the id an owner change must be addressed to. For a smart wallet\nthis is the embedded EOA beneath it, since a smart wallet has no Privy\nwallet id and no quorum of its own.", "type": "string" }, "threshold": { "description": "Threshold is how many quorum members must sign; AuthorizationKeys counts\nthe app-held keys among them.", "type": "integer" }, "user_is_member": { "type": "boolean" } } }, "internal_delivery_http_handler.WalletResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/internal_delivery_http_handler.WalletView" }, "success": { "type": "boolean", "example": true } } }, "internal_delivery_http_handler.WalletView": { "type": "object", "properties": { "address": { "type": "string" }, "chain_type": { "description": "ChainType is \"ethereum\" today.", "type": "string" }, "created_at": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "is_primary": { "type": "boolean" }, "label": { "type": "string" }, "owner_quorum_id": { "description": "OwnerQuorumID is the Privy key quorum owning the wallet, present only when\nthe wallet was minted quorum-owned. Its presence tells a client that this\nwallet cannot be signed for by the user's session alone — the app key is a\nrequired co-signer — and the client needs the id itself to build the\nauthorization payload. Omitted for user-owned wallets, i.e. all of them\nbefore wallet-send-enforcement is switched on for a tenant.", "type": "string" }, "wallet_kind": { "description": "WalletKind is \"smart\" (the primary, paymaster-sponsored) or \"embedded\"\n(a secondary EOA that pays its own gas). Clients use it to decide whether\nto warn about gas before a send.", "type": "string" } } }, "internal_delivery_http_handler.bulkItem": { "type": "object", "properties": { "error": { "type": "string" }, "id": { "type": "string" }, "status": { "description": "ok | forbidden | error", "type": "string" } } } }, "securityDefinitions": { "ApiKeyAuth": { "type": "apiKey", "name": "X-API-Key", "in": "header" }, "BearerAuth": { "type": "apiKey", "name": "Authorization", "in": "header" } } }