{ "schemes": [ "https" ], "swagger": "2.0", "info": { "description": "B2B SaaS identity and age verification API. Three route groups: /api/v1 (SDK, API key auth), /dashboard/v1 (dashboard, JWT auth), /admin/v1 (admin panel, JWT + 2FA auth).", "title": "Xident API", "contact": {}, "version": "1.0" }, "host": "api.xident.io", "basePath": "/", "paths": { "/.well-known/jwks.json": { "get": { "description": "Returns the public keys used to verify OAuth token signatures. Cached for 1 hour.", "produces": [ "application/json" ], "tags": [ "OAuth OIDC" ], "summary": "Get JSON Web Key Set", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/.well-known/openid-configuration": { "get": { "description": "Returns the OIDC discovery document with issuer, endpoints, supported scopes, and signing algorithms.", "produces": [ "application/json" ], "tags": [ "OAuth OIDC" ], "summary": "Get OpenID Connect discovery document", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all portal user accounts with pagination, search, and filters.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "List portal accounts", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Search by email or display name", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by status (active, suspended, locked, pending_deletion)", "name": "status", "in": "query" }, { "type": "boolean", "description": "Filter by email verified status", "name": "verified", "in": "query" }, { "type": "string", "description": "Filter from date (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "Filter to date (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/stats": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns aggregate statistics for all portal user accounts.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "Get portal account statistics", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get detailed overview of a specific portal account including age brackets, counts, and recent logins.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "Get portal account details", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently delete a portal account and all related data via CASCADE. This is irreversible.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "Delete portal account (GDPR)", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/{id}/connections": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get paginated list of sites connected to a portal account.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "List account connections", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/{id}/force-logout": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Revoke all active sessions for a portal account.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "Force logout portal account", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/{id}/login-history": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get paginated login attempts for a portal account.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "List account login history", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/{id}/notifications": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get paginated notifications for a portal account.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "List account notifications", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/{id}/passkeys": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get all WebAuthn passkeys registered to a portal account.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "List account passkeys", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/{id}/sessions": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get all active sessions for a portal account.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "List account sessions", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/{id}/suspend": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Deactivate a portal account, revoking all sessions.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "Suspend portal account", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/{id}/unlock": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Reset failed login count and clear lockout for a portal account.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "Unlock portal account", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/accounts/{id}/unsuspend": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Reactivate a previously suspended portal account.", "produces": [ "application/json" ], "tags": [ "Admin Accounts" ], "summary": "Unsuspend portal account", "parameters": [ { "type": "integer", "description": "Account ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/analytics/comparison": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns current period vs previous period stats with % changes, funnel data, and dual time series for overlay charts.", "produces": [ "application/json" ], "tags": [ "Admin Analytics" ], "summary": "Get period-over-period comparison analytics", "parameters": [ { "type": "integer", "default": 30, "description": "Number of days per period", "name": "days", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/analytics/overview": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get platform-wide analytics overview including total tenants, users, verifications, and revenue.", "produces": [ "application/json" ], "tags": [ "Admin Analytics" ], "summary": "Get analytics overview", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/analytics/verifications": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get verification statistics over a specified number of days (default 30, max 365).", "produces": [ "application/json" ], "tags": [ "Admin Analytics" ], "summary": "Get verification statistics", "parameters": [ { "type": "integer", "default": 30, "description": "Number of days to look back", "name": "days", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/audit": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List audit log entries with pagination and optional filters by admin user, action, target type, and date range.", "produces": [ "application/json" ], "tags": [ "Admin Audit" ], "summary": "List audit logs", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "integer", "description": "Filter by admin user ID", "name": "admin_user_id", "in": "query" }, { "type": "string", "description": "Filter by action", "name": "action", "in": "query" }, { "type": "string", "description": "Filter by target type", "name": "target_type", "in": "query" }, { "type": "string", "description": "Filter from date (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "Filter to date (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/audit/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a specific audit log entry by ID.", "produces": [ "application/json" ], "tags": [ "Admin Audit" ], "summary": "Get audit log entry", "parameters": [ { "type": "integer", "description": "Audit log ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/2fa/challenge": { "post": { "description": "Verify a TOTP code after login when 2FA is enabled. Requires the challenge_token from login response.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Complete 2FA challenge during login", "parameters": [ { "description": "2FA challenge", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.admin2FAChallengeRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/admin.adminLoginResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/2fa/disable": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Disable 2FA for the authenticated admin user. Requires password re-authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Disable two-factor authentication", "parameters": [ { "description": "Current password for re-authentication", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.disable2FARequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/2fa/setup": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Generate a TOTP secret server-side and return it with a provisioning URI. Must be followed by Verify2FA to enable.", "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Set up two-factor authentication", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/admin.setup2FAResponse" } } } ] } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/2fa/status": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Check whether two-factor authentication is enabled for the authenticated admin user.", "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Get 2FA status", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/2fa/verify": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Verify a TOTP code against the stored secret and enable 2FA for the admin user.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Verify and enable two-factor authentication", "parameters": [ { "description": "TOTP verification code", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.verify2FARequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/forgot-password": { "post": { "description": "Send a password reset email. Always returns 200 to prevent email enumeration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Request admin password reset", "parameters": [ { "description": "Email address", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.adminForgotPasswordRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/login": { "post": { "description": "Authenticate admin user with email and password. Returns JWT tokens. May require 2FA verification.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Login to admin panel", "parameters": [ { "description": "Login credentials", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.adminLoginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/admin.adminLoginResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/logout": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Invalidate the current session. Client should discard tokens.", "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Logout admin user", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/logout-all": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Invalidate all active sessions for this admin user. Stores a revocation timestamp in Redis;", "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Logout from all devices", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/me": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Return the authenticated admin user's profile information.", "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Get current admin user", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/admin.adminUserDTO" } } } ] } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/passkey/authenticate/begin": { "post": { "description": "Start the WebAuthn authentication ceremony. Optionally provide email for non-discoverable flow.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Passkeys" ], "summary": "Begin passkey authentication", "parameters": [ { "description": "Optional email for non-discoverable flow", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/admin.authBeginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/passkey/authenticate/finish": { "post": { "description": "Complete the WebAuthn authentication ceremony. Returns JWT tokens on success. Bypasses 2FA. Requires session ID via X-Session-ID header or query param.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Passkeys" ], "summary": "Finish passkey authentication", "parameters": [ { "type": "string", "description": "WebAuthn session ID", "name": "X-Session-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/admin.adminLoginResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/passkey/register/begin": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Start the WebAuthn registration ceremony. Returns credential creation options and a session ID.", "produces": [ "application/json" ], "tags": [ "Admin Passkeys" ], "summary": "Begin passkey registration", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/passkey/register/finish": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Complete the WebAuthn registration ceremony. Requires session ID via X-Session-ID header or query param. Optionally set passkey name via X-Passkey-Name header.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Passkeys" ], "summary": "Finish passkey registration", "parameters": [ { "type": "string", "description": "WebAuthn session ID", "name": "X-Session-ID", "in": "header", "required": true }, { "type": "string", "description": "Passkey display name", "name": "X-Passkey-Name", "in": "header" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/admin.passkeyDTO" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/passkeys": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all registered passkeys for the authenticated admin user.", "produces": [ "application/json" ], "tags": [ "Admin Passkeys" ], "summary": "List passkeys", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/admin.passkeyDTO" } } } } ] } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/passkeys/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Remove a registered passkey for the authenticated admin user.", "produces": [ "application/json" ], "tags": [ "Admin Passkeys" ], "summary": "Delete passkey", "parameters": [ { "type": "integer", "description": "Passkey ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Rename a registered passkey for the authenticated admin user.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Passkeys" ], "summary": "Update passkey name", "parameters": [ { "type": "integer", "description": "Passkey ID", "name": "id", "in": "path", "required": true }, { "description": "New passkey name", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.updatePasskeyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/refresh": { "post": { "description": "Exchange a valid refresh token for a new access token.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Refresh access token", "parameters": [ { "description": "Refresh token", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.adminRefreshRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/auth/reset-password": { "post": { "description": "Validate the reset token and set a new password.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Auth" ], "summary": "Reset admin password with token", "parameters": [ { "description": "Reset token and new password", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.adminResetPasswordRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/billing/metrics": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all billable metrics from Lago.", "produces": [ "application/json" ], "tags": [ "Admin Billing Plans" ], "summary": "List billable metrics", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/billing/periods": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns billing periods, optionally filtered by tenant.", "produces": [ "application/json" ], "tags": [ "Admin Billing Audit" ], "summary": "List billing periods", "parameters": [ { "type": "integer", "description": "Filter by tenant ID", "name": "tenant_id", "in": "query" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/billing/plans": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all billing plans from Lago with charges.", "produces": [ "application/json" ], "tags": [ "Admin Billing Plans" ], "summary": "List billing plans", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/billing/plans/{code}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a single billing plan by code with its charges.", "produces": [ "application/json" ], "tags": [ "Admin Billing Plans" ], "summary": "Get billing plan", "parameters": [ { "type": "string", "description": "Plan code", "name": "code", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update a billing plan's pricing and charges in Lago.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Billing Plans" ], "summary": "Update billing plan", "parameters": [ { "type": "string", "description": "Plan code", "name": "code", "in": "path", "required": true }, { "description": "Plan update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.LagoPlanUpdate" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/billing/request-logs": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated API request logs for a tenant.", "produces": [ "application/json" ], "tags": [ "Admin Billing Audit" ], "summary": "List API request logs", "parameters": [ { "type": "integer", "description": "Tenant ID", "name": "tenant_id", "in": "query", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/billing/tenants/{id}/plan": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Change a tenant's billing plan in Lago.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Billing Plans" ], "summary": "Change tenant plan", "parameters": [ { "type": "integer", "description": "Tenant ID", "name": "id", "in": "path", "required": true }, { "description": "New plan {plan_code: string}", "name": "body", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/billing/usage-events": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated usage events with optional filters.", "produces": [ "application/json" ], "tags": [ "Admin Billing Audit" ], "summary": "List usage events", "parameters": [ { "type": "integer", "description": "Filter by tenant ID", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "Filter by event type", "name": "event_type", "in": "query" }, { "type": "string", "description": "Billing period (YYYY-MM)", "name": "period", "in": "query" }, { "type": "boolean", "description": "Only billable events", "name": "billable_only", "in": "query" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/billing/usage-summary": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns aggregated billing data for a tenant and period.", "produces": [ "application/json" ], "tags": [ "Admin Billing Audit" ], "summary": "Get usage summary", "parameters": [ { "type": "integer", "description": "Tenant ID", "name": "tenant_id", "in": "query", "required": true }, { "type": "string", "default": "current", "description": "Billing period (YYYY-MM)", "name": "period", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/blacklist": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List active face blacklist entries with pagination. Requires tenant_id filter.", "produces": [ "application/json" ], "tags": [ "Admin Blacklist" ], "summary": "List blacklist entries", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "integer", "description": "Tenant ID", "name": "tenant_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Add a face embedding to the blacklist.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Blacklist" ], "summary": "Add to blacklist", "parameters": [ { "description": "Blacklist entry", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.addBlacklistRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/blacklist/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Deactivate a face blacklist entry.", "produces": [ "application/json" ], "tags": [ "Admin Blacklist" ], "summary": "Remove from blacklist", "parameters": [ { "type": "integer", "description": "Blacklist entry ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "description": "Tenant ID", "name": "tenant_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/content-categories": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all content categories (including inactive) for admin management. Includes country rule count per category.", "produces": [ "application/json" ], "tags": [ "Admin Content Categories" ], "summary": "List content categories", "parameters": [ { "type": "string", "description": "Search by name or slug", "name": "search", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new content category with default verification settings.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Content Categories" ], "summary": "Create content category", "parameters": [ { "description": "Category data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.createCategoryRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/content-categories/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a single content category by ID with its country rule count.", "produces": [ "application/json" ], "tags": [ "Admin Content Categories" ], "summary": "Get content category", "parameters": [ { "type": "integer", "description": "Category ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Updates an existing content category.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Content Categories" ], "summary": "Update content category", "parameters": [ { "type": "integer", "description": "Category ID", "name": "id", "in": "path", "required": true }, { "description": "Updated category data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.createCategoryRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently removes a content category. Fails if API keys reference this category.", "produces": [ "application/json" ], "tags": [ "Admin Content Categories" ], "summary": "Delete content category", "parameters": [ { "type": "integer", "description": "Category ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/content-categories/{id}/country-rules": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated country-specific rules for a content category.", "produces": [ "application/json" ], "tags": [ "Admin Content Categories" ], "summary": "List country rules for a category", "parameters": [ { "type": "integer", "description": "Category ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Search by country code", "name": "search", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new country-specific verification rule for a content category.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Content Categories" ], "summary": "Add country rule to category", "parameters": [ { "type": "integer", "description": "Category ID", "name": "id", "in": "path", "required": true }, { "description": "Country rule data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.createCountryRuleRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/country-rules/{id}": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Updates an existing country-specific content rule.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Content Categories" ], "summary": "Update country rule", "parameters": [ { "type": "integer", "description": "Country rule ID", "name": "id", "in": "path", "required": true }, { "description": "Updated rule data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.createCountryRuleRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently removes a country-specific content rule.", "produces": [ "application/json" ], "tags": [ "Admin Content Categories" ], "summary": "Delete country rule", "parameters": [ { "type": "integer", "description": "Country rule ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/dpa/acceptances": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all DPA acceptances across tenants, with optional version filter.", "produces": [ "application/json" ], "tags": [ "Admin DPA" ], "summary": "List DPA acceptances", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Filter by DPA version", "name": "version", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/dpa/acceptances/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "Admin DPA" ], "summary": "Get DPA acceptance detail", "parameters": [ { "type": "integer", "description": "Acceptance ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/dpa/pending": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List active tenants that haven't accepted the current DPA version.", "produces": [ "application/json" ], "tags": [ "Admin DPA" ], "summary": "List tenants without DPA", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/dpa/remind": { "post": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin DPA" ], "summary": "Send DPA reminder", "parameters": [ { "description": "Tenant ID", "name": "body", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/dpa/remind-all": { "post": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "Admin DPA" ], "summary": "Send DPA reminders to all pending tenants", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/dpa/stats": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "Admin DPA" ], "summary": "Get DPA stats", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/feedback": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Admin Feedback" ], "summary": "List all feedback", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Filter by source (portal, widget)", "name": "source", "in": "query" }, { "type": "integer", "description": "Filter by rating (1-5)", "name": "rating", "in": "query" }, { "type": "string", "description": "Start date (ISO)", "name": "start_date", "in": "query" }, { "type": "string", "description": "End date (ISO)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/feedback/stats": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Admin Feedback" ], "summary": "Feedback statistics", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/jobs": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List River jobs with pagination and optional filters by state, kind, and queue.", "produces": [ "application/json" ], "tags": [ "Admin Jobs" ], "summary": "List jobs", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Filter by job state (available, running, completed, discarded, etc.)", "name": "state", "in": "query" }, { "type": "string", "description": "Filter by job kind", "name": "kind", "in": "query" }, { "type": "string", "description": "Filter by queue name", "name": "queue", "in": "query" }, { "type": "string", "description": "Filter from date (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "Filter to date (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/jobs/stats": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get aggregate statistics for all River job queues including counts by state.", "produces": [ "application/json" ], "tags": [ "Admin Jobs" ], "summary": "Get job queue statistics", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/jobs/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get detailed information about a specific River job by ID.", "produces": [ "application/json" ], "tags": [ "Admin Jobs" ], "summary": "Get job details", "parameters": [ { "type": "integer", "description": "Job ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/jobs/{id}/cancel": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Cancel a pending or running job.", "produces": [ "application/json" ], "tags": [ "Admin Jobs" ], "summary": "Cancel a job", "parameters": [ { "type": "integer", "description": "Job ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/jobs/{id}/retry": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Queue a failed or discarded job for retry.", "produces": [ "application/json" ], "tags": [ "Admin Jobs" ], "summary": "Retry a job", "parameters": [ { "type": "integer", "description": "Job ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/knowledge-base": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all knowledge base entries with pagination, ordered by category and priority.", "produces": [ "application/json" ], "tags": [ "Admin Knowledge Base" ], "summary": "List knowledge base entries", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new FAQ entry for the AI support agent knowledge base.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Knowledge Base" ], "summary": "Create knowledge base entry", "parameters": [ { "description": "Knowledge base entry", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.createKnowledgeBaseRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/knowledge-base/backfill-embeddings": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Generate embeddings for all active KB entries that don't have one yet.", "produces": [ "application/json" ], "tags": [ "Admin Knowledge Base" ], "summary": "Backfill KB embeddings", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/knowledge-base/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a single knowledge base entry by ID.", "produces": [ "application/json" ], "tags": [ "Admin Knowledge Base" ], "summary": "Get knowledge base entry", "parameters": [ { "type": "integer", "description": "Entry ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update an existing FAQ entry in the AI support agent knowledge base.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Knowledge Base" ], "summary": "Update knowledge base entry", "parameters": [ { "type": "integer", "description": "Entry ID", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.updateKnowledgeBaseRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently delete a FAQ entry from the AI support agent knowledge base.", "produces": [ "application/json" ], "tags": [ "Admin Knowledge Base" ], "summary": "Delete knowledge base entry", "parameters": [ { "type": "integer", "description": "Entry ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/notifications": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all notifications with pagination.", "produces": [ "application/json" ], "tags": [ "Admin Notifications" ], "summary": "List notifications", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create and send a notification to dashboard members.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Notifications" ], "summary": "Send notification", "parameters": [ { "description": "Notification data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.CreateNotificationRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/notifications/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a single notification with read statistics.", "produces": [ "application/json" ], "tags": [ "Admin Notifications" ], "summary": "Get notification", "parameters": [ { "type": "integer", "description": "Notification ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft-delete a notification.", "produces": [ "application/json" ], "tags": [ "Admin Notifications" ], "summary": "Delete notification", "parameters": [ { "type": "integer", "description": "Notification ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/oauth/clients": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all OAuth clients across all tenants with pagination (admin view).", "produces": [ "application/json" ], "tags": [ "Admin OAuth" ], "summary": "List all OAuth clients", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page (max 100)", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/oauth/clients/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a specific OAuth client by ID (admin view, no tenant scoping).", "produces": [ "application/json" ], "tags": [ "Admin OAuth" ], "summary": "Get an OAuth client", "parameters": [ { "type": "string", "description": "OAuth client ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/oauth/clients/{id}/suspend": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Suspends an OAuth client, preventing it from being used for new authorizations.", "produces": [ "application/json" ], "tags": [ "Admin OAuth" ], "summary": "Suspend an OAuth client", "parameters": [ { "type": "string", "description": "OAuth client ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/oauth/stats": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns global OAuth usage statistics including total and active client counts.", "produces": [ "application/json" ], "tags": [ "Admin OAuth" ], "summary": "Get global OAuth stats", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/permissions": { "get": { "security": [ { "AdminBearerAuth": [] } ], "description": "Returns all admin permissions organized by resource group, for role management UI", "produces": [ "application/json" ], "tags": [ "Admin Roles" ], "summary": "List all admin permissions", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/permissions.AdminPermissionGroup" } } } } ] } } } } }, "/admin/v1/pilot/onboard": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Tags tenants as pilot, grants credits, optionally sends welcome email.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Pilot" ], "summary": "Batch onboard tenants to pilot program", "parameters": [ { "description": "Pilot onboard request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.OnboardRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/promos": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "Admin Promos" ], "summary": "List all promo codes", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new promotional code that grants credits when redeemed.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Promos" ], "summary": "Create a promo code", "parameters": [ { "description": "Promo code details", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.CreatePromoRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/promos/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a promo code with redemption summary.", "produces": [ "application/json" ], "tags": [ "Admin Promos" ], "summary": "Get promo code details", "parameters": [ { "type": "integer", "description": "Promo code ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Promos" ], "summary": "Update/deactivate a promo code", "parameters": [ { "type": "integer", "description": "Promo code ID", "name": "id", "in": "path", "required": true }, { "description": "Update fields", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.UpdatePromoRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/promos/{id}/redemptions": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "Admin Promos" ], "summary": "List promo code redemptions", "parameters": [ { "type": "integer", "description": "Promo code ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/review-queue": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List review queue items with optional status/priority filters.", "produces": [ "application/json" ], "tags": [ "Admin Review Queue" ], "summary": "List review queue items", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "string", "description": "Filter by priority", "name": "priority", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/review-queue/stats": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get aggregate counts of review queue items by status.", "produces": [ "application/json" ], "tags": [ "Admin Review Queue" ], "summary": "Review queue statistics", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/review-queue/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a specific review queue item by ID.", "produces": [ "application/json" ], "tags": [ "Admin Review Queue" ], "summary": "Get review queue item", "parameters": [ { "type": "integer", "description": "Review item ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/review-queue/{id}/assign": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Assign a review item to an admin user. Self-assigns if no admin_user_id.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Review Queue" ], "summary": "Assign review item", "parameters": [ { "type": "integer", "description": "Review item ID", "name": "id", "in": "path", "required": true }, { "description": "Admin user to assign", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/admin.assignReviewRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/review-queue/{id}/documents": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns presigned GET URLs for document images (front, back, selfie) attached to a review item.", "produces": [ "application/json" ], "tags": [ "Admin Review Queue" ], "summary": "Get review item documents", "parameters": [ { "type": "integer", "description": "Review item ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/review-queue/{id}/resolve": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Approve or reject a review item.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Review Queue" ], "summary": "Resolve review item", "parameters": [ { "type": "integer", "description": "Review item ID", "name": "id", "in": "path", "required": true }, { "description": "Resolution details", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.resolveReviewRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/roles": { "get": { "security": [ { "AdminBearerAuth": [] } ], "description": "Returns all admin roles with their permissions and user counts", "produces": [ "application/json" ], "tags": [ "Admin Roles" ], "summary": "List admin roles", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/services.AdminRoleDTO" } } } } ] } } } }, "post": { "security": [ { "AdminBearerAuth": [] } ], "description": "Creates a new admin role with the specified permissions. Escalation check prevents granting permissions the requester doesn't have.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Roles" ], "summary": "Create a custom admin role", "parameters": [ { "description": "Role data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.createRoleRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/services.AdminRoleDTO" } } } ] } } } } }, "/admin/v1/roles/{id}": { "get": { "security": [ { "AdminBearerAuth": [] } ], "description": "Returns a single admin role with permissions and user count", "produces": [ "application/json" ], "tags": [ "Admin Roles" ], "summary": "Get admin role detail", "parameters": [ { "type": "integer", "description": "Role ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/services.AdminRoleDTO" } } } ] } } } }, "put": { "security": [ { "AdminBearerAuth": [] } ], "description": "Updates a role's name, description, and permissions. System roles can be updated (except super_admin). Invalidates affected user sessions.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Roles" ], "summary": "Update admin role permissions", "parameters": [ { "type": "integer", "description": "Role ID", "name": "id", "in": "path", "required": true }, { "description": "Role data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.updateRoleRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/services.AdminRoleDTO" } } } ] } } } }, "delete": { "security": [ { "AdminBearerAuth": [] } ], "description": "Deletes a custom (non-system) admin role. Fails if any users are assigned to it.", "produces": [ "application/json" ], "tags": [ "Admin Roles" ], "summary": "Delete a custom admin role", "parameters": [ { "type": "integer", "description": "Role ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/support/tickets": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all support tickets with pagination and optional status filter.", "produces": [ "application/json" ], "tags": [ "Admin Support" ], "summary": "List support tickets", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Filter by ticket status", "name": "status", "in": "query" }, { "type": "string", "description": "Filter from date (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "Filter to date (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/support/tickets/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a specific support ticket by ID including messages and metadata.", "produces": [ "application/json" ], "tags": [ "Admin Support" ], "summary": "Get support ticket", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/support/tickets/{id}/assign": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Assign a support ticket to an admin user. If no admin_user_id is provided, self-assigns.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Support" ], "summary": "Assign support ticket", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true }, { "description": "Admin user to assign (omit for self-assign)", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/admin.assignTicketRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/support/tickets/{id}/attachments/presign": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Generate a presigned S3 URL for uploading a file attachment to a support ticket. Allowed types: png, jpeg, gif, webp, pdf.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Support" ], "summary": "Get presigned upload URL for ticket attachment", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true }, { "description": "Attachment metadata", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.presignAttachmentRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/admin.presignAttachmentResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/support/tickets/{id}/note": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Add an internal staff-only note to a support ticket. Not visible to the customer.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Support" ], "summary": "Add internal note to ticket", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true }, { "description": "Note message and optional attachments", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.internalNoteRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/support/tickets/{id}/reply": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Send a staff reply to a support ticket. Supports optional file attachments.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Support" ], "summary": "Reply to support ticket", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true }, { "description": "Reply message and optional attachments", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.ticketReplyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/support/tickets/{id}/status": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update the status of a support ticket (e.g., open, in_progress, resolved, closed).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Support" ], "summary": "Change ticket status", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true }, { "description": "New ticket status", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.changeStatusRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/surveys": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all surveys with pagination and optional search.", "produces": [ "application/json" ], "tags": [ "Admin Surveys" ], "summary": "List surveys", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Search by title or slug", "name": "search", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new survey from a JSON schema.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Surveys" ], "summary": "Create survey", "parameters": [ { "description": "Survey data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.CreateSurveyRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/surveys/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a survey with its aggregated results.", "produces": [ "application/json" ], "tags": [ "Admin Surveys" ], "summary": "Get survey detail", "parameters": [ { "type": "integer", "description": "Survey ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update an existing survey.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Surveys" ], "summary": "Update survey", "parameters": [ { "type": "integer", "description": "Survey ID", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.UpdateSurveyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/surveys/{id}/export": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Download all responses for a survey as a CSV file.", "produces": [ "text/csv" ], "tags": [ "Admin Surveys" ], "summary": "Export survey responses as CSV", "parameters": [ { "type": "integer", "description": "Survey ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/surveys/{id}/recompute": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Force recompute aggregated results for a survey.", "produces": [ "application/json" ], "tags": [ "Admin Surveys" ], "summary": "Recompute aggregation", "parameters": [ { "type": "integer", "description": "Survey ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/surveys/{id}/responses": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List raw responses for a survey with pagination.", "produces": [ "application/json" ], "tags": [ "Admin Surveys" ], "summary": "List survey responses", "parameters": [ { "type": "integer", "description": "Survey ID", "name": "id", "in": "path" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/system/cache/clear": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Flush all entries from the Redis application cache.", "produces": [ "application/json" ], "tags": [ "Admin System" ], "summary": "Clear application cache", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/system/health": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get system health status including database, Redis, and S3 connectivity.", "produces": [ "application/json" ], "tags": [ "Admin System" ], "summary": "Get system health", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/system/status": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get comprehensive system status with DB pool stats, Redis memory, and queue depth.", "produces": [ "application/json" ], "tags": [ "Admin System" ], "summary": "Get detailed system status", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tags/members": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all predefined member tags.", "produces": [ "application/json" ], "tags": [ "Admin Tags" ], "summary": "List predefined member tags", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tags/members/used": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns member tags currently in use with counts.", "produces": [ "application/json" ], "tags": [ "Admin Tags" ], "summary": "List member tags in use", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tags/tenants": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all predefined tenant tags.", "produces": [ "application/json" ], "tags": [ "Admin Tags" ], "summary": "List predefined tenant tags", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tags/tenants/used": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns tenant tags currently in use with counts.", "produces": [ "application/json" ], "tags": [ "Admin Tags" ], "summary": "List tenant tags in use", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tenants": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all tenants with pagination and optional search filter.", "produces": [ "application/json" ], "tags": [ "Admin Tenants" ], "summary": "List tenants", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Search by name or email", "name": "search", "in": "query" }, { "type": "string", "description": "Filter from date (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "Filter to date (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tenants/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get detailed overview of a specific tenant including usage stats.", "produces": [ "application/json" ], "tags": [ "Admin Tenants" ], "summary": "Get tenant details", "parameters": [ { "type": "integer", "description": "Tenant ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tenants/{id}/credits": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns current credit balance and paginated ledger history.", "produces": [ "application/json" ], "tags": [ "Admin Credits" ], "summary": "Get tenant credit balance and history", "parameters": [ { "type": "integer", "description": "Tenant ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Manually add verification credits to a tenant's balance.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Credits" ], "summary": "Grant credits to a tenant", "parameters": [ { "type": "integer", "description": "Tenant ID", "name": "id", "in": "path", "required": true }, { "description": "Credit grant details", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.GrantCreditsRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tenants/{id}/suspend": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Suspend a tenant, disabling all their API keys and access.", "produces": [ "application/json" ], "tags": [ "Admin Tenants" ], "summary": "Suspend tenant", "parameters": [ { "type": "integer", "description": "Tenant ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tenants/{id}/tags": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Replace the tags on a tenant. Tags are validated against the predefined list.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Tags" ], "summary": "Update tenant tags", "parameters": [ { "type": "integer", "description": "Tenant ID", "name": "id", "in": "path", "required": true }, { "description": "Tags array", "name": "body", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tenants/{id}/unsuspend": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Reactivate a previously suspended tenant, restoring API access.", "produces": [ "application/json" ], "tags": [ "Admin Tenants" ], "summary": "Unsuspend tenant", "parameters": [ { "type": "integer", "description": "Tenant ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/tenants/{id}/usage-events": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns usage events for a specific tenant (admin convenience endpoint).", "produces": [ "application/json" ], "tags": [ "Admin Billing Audit" ], "summary": "List usage events for a specific tenant", "parameters": [ { "type": "integer", "description": "Tenant ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/users/admin/{id}/role": { "patch": { "security": [ { "AdminBearerAuth": [] } ], "description": "Assigns a new role to an admin user. Forces re-authentication. Audit logged.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Roles" ], "summary": "Change an admin user's role", "parameters": [ { "type": "integer", "description": "Admin User ID", "name": "id", "in": "path", "required": true }, { "description": "New role", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.assignRoleRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/users/dashboard": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List tenant dashboard users (members) with pagination, optional search and tenant filter.", "produces": [ "application/json" ], "tags": [ "Admin Users" ], "summary": "List dashboard users", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Search by email or name", "name": "search", "in": "query" }, { "type": "integer", "description": "Filter by tenant ID", "name": "tenant_id", "in": "query" }, { "type": "string", "description": "Filter from date (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "Filter to date (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/users/dashboard/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a specific dashboard user (member) by ID, including their role.", "produces": [ "application/json" ], "tags": [ "Admin Users" ], "summary": "Get dashboard user", "parameters": [ { "type": "integer", "description": "Member ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/users/dashboard/{id}/suspend": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Deactivate a dashboard user, preventing them from logging in.", "produces": [ "application/json" ], "tags": [ "Admin Users" ], "summary": "Suspend dashboard user", "parameters": [ { "type": "integer", "description": "Member ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/users/dashboard/{id}/tags": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Replace the tags on a dashboard member. Tags are validated against the predefined list.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Tags" ], "summary": "Update member tags", "parameters": [ { "type": "integer", "description": "Member ID", "name": "id", "in": "path", "required": true }, { "description": "Tags array", "name": "body", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/users/dashboard/{id}/unsuspend": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Reactivate a previously suspended dashboard user.", "produces": [ "application/json" ], "tags": [ "Admin Users" ], "summary": "Unsuspend dashboard user", "parameters": [ { "type": "integer", "description": "Member ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/waitlist": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List waiting list entries with pagination and optional search.", "produces": [ "application/json" ], "tags": [ "Admin Waitlist" ], "summary": "List waitlist entries", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Search by email", "name": "search", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/waitlist/announce": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Queue announcement emails to all unnotified waitlist entries.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin Waitlist" ], "summary": "Send launch announcement", "parameters": [ { "description": "Announcement content", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/admin.announceRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/waitlist/export": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Download all waiting list entries as a CSV file.", "produces": [ "text/csv" ], "tags": [ "Admin Waitlist" ], "summary": "Export waitlist as CSV", "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/waitlist/stats": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get aggregate counts for the waiting list.", "produces": [ "application/json" ], "tags": [ "Admin Waitlist" ], "summary": "Get waitlist stats", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/waitlist/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft-delete a waiting list entry.", "produces": [ "application/json" ], "tags": [ "Admin Waitlist" ], "summary": "Delete waitlist entry", "parameters": [ { "type": "integer", "description": "Entry ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/webhooks": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated webhooks across all tenants (admin view).", "produces": [ "application/json" ], "tags": [ "Admin Webhooks" ], "summary": "List all webhooks", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/webhooks/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a webhook with recent deliveries (admin view).", "produces": [ "application/json" ], "tags": [ "Admin Webhooks" ], "summary": "Get webhook details", "parameters": [ { "type": "integer", "description": "Webhook ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/webhooks/{id}/deliveries": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated delivery log for a webhook (admin view).", "produces": [ "application/json" ], "tags": [ "Admin Webhooks" ], "summary": "List webhook deliveries", "parameters": [ { "type": "integer", "description": "Webhook ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/admin/v1/webhooks/{id}/deliveries/{did}/resend": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Re-enqueues a specific delivery (admin view).", "produces": [ "application/json" ], "tags": [ "Admin Webhooks" ], "summary": "Resend a delivery", "parameters": [ { "type": "integer", "description": "Webhook ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "description": "Delivery ID", "name": "did", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/account": { "delete": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "tags": [ "Portal Account" ], "summary": "Request account deletion", "parameters": [ { "description": "Confirmation (must be 'DELETE')", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.deleteAccountRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/account/cancel-deletion": { "post": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Account" ], "summary": "Cancel account deletion", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/account/export": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Account" ], "summary": "Export account data", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/account/manual-review": { "post": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Verify" ], "summary": "Request manual review of failed verification", "parameters": [ { "description": "Reason (10-1000 chars)", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.manualReviewRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/age-verifications": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Profile" ], "summary": "List age verifications", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/app.ageVerificationDTO" } } } } ] } } } } }, "/app/v1/auth/activate": { "post": { "description": "Set password and activate account from quick-register activation email", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Auth" ], "summary": "Activate account", "parameters": [ { "description": "Activation data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.activateAccountRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/auth/forgot-password": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Auth" ], "summary": "Request password reset", "parameters": [ { "description": "Email", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.forgotPasswordRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/auth/login": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Auth" ], "summary": "Portal login", "parameters": [ { "description": "Credentials", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.appLoginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.appLoginResponse" } } } ] } } } } }, "/app/v1/auth/logout": { "post": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "tags": [ "Portal Auth" ], "summary": "Logout", "parameters": [ { "description": "Refresh token to invalidate", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.appRefreshRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/auth/passkey/authenticate/begin": { "post": { "produces": [ "application/json" ], "tags": [ "Portal Passkeys" ], "summary": "Begin passkey authentication", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/auth/passkey/authenticate/finish": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Passkeys" ], "summary": "Finish passkey authentication", "parameters": [ { "type": "string", "description": "Session ID from authenticate/begin", "name": "X-Session-ID", "in": "header" }, { "type": "string", "description": "Session ID from authenticate/begin", "name": "session_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.appLoginResponse" } } } ] } } } } }, "/app/v1/auth/refresh": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Auth" ], "summary": "Refresh tokens", "parameters": [ { "description": "Refresh token", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.appRefreshRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.appLoginResponse" } } } ] } } } } }, "/app/v1/auth/register": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Auth" ], "summary": "Portal registration", "parameters": [ { "description": "Registration data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.appRegisterRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.appUserDTO" } } } ] } } } } }, "/app/v1/auth/resend-verification": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Auth" ], "summary": "Resend verification email", "parameters": [ { "description": "Email", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.resendVerificationRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/auth/reset-password": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Auth" ], "summary": "Reset password", "parameters": [ { "description": "Reset token and new password", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.resetPasswordRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/auth/social/{provider}/begin": { "get": { "tags": [ "Portal Auth" ], "summary": "Initiate social OAuth login", "parameters": [ { "type": "string", "description": "OAuth provider (google, apple, microsoft)", "name": "provider", "in": "path", "required": true }, { "type": "string", "description": "Frontend callback URL", "name": "redirect_uri", "in": "query", "required": true } ], "responses": { "302": { "description": "Found" } } } }, "/app/v1/auth/social/{provider}/callback": { "get": { "tags": [ "Portal Auth" ], "summary": "Handle OAuth callback", "parameters": [ { "type": "string", "description": "OAuth provider", "name": "provider", "in": "path", "required": true }, { "type": "string", "description": "Authorization code", "name": "code", "in": "query", "required": true }, { "type": "string", "description": "OAuth state", "name": "state", "in": "query", "required": true } ], "responses": { "302": { "description": "Found" } } } }, "/app/v1/auth/verify-email": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Auth" ], "summary": "Verify email address", "parameters": [ { "description": "Verification token", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.verifyEmailRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/connections": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Connections" ], "summary": "List authorized apps", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/app.connectionDTO" } } } } ] } } } } }, "/app/v1/connections/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Connections" ], "summary": "Revoke app access", "parameters": [ { "type": "integer", "description": "Consent grant ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/conversations": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated support conversations for the authenticated portal account.", "produces": [ "application/json" ], "tags": [ "Portal Support" ], "summary": "List support conversations", "parameters": [ { "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new support conversation with an initial message.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Support" ], "summary": "Start a new conversation", "parameters": [ { "description": "Conversation details", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.createConversationRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/conversations/unread": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the total number of unread messages across all conversations.", "produces": [ "application/json" ], "tags": [ "Portal Support" ], "summary": "Get unread count", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/conversations/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a single conversation with all its messages.", "produces": [ "application/json" ], "tags": [ "Portal Support" ], "summary": "Get conversation", "parameters": [ { "type": "string", "description": "Conversation ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/conversations/{id}/attachments/presign": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Generates a presigned S3 URL for uploading a file attachment to a conversation.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Support" ], "summary": "Get presigned upload URL for conversation attachment", "parameters": [ { "type": "string", "description": "Conversation ID", "name": "id", "in": "path", "required": true }, { "description": "File metadata", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.portalPresignAttachmentRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.portalPresignAttachmentResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/conversations/{id}/close": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Closes an open conversation.", "produces": [ "application/json" ], "tags": [ "Portal Support" ], "summary": "Close conversation", "parameters": [ { "type": "string", "description": "Conversation ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/conversations/{id}/messages": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Adds a message to an existing conversation.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Support" ], "summary": "Send a message", "parameters": [ { "type": "string", "description": "Conversation ID", "name": "id", "in": "path", "required": true }, { "description": "Message content", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.sendMessageRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/conversations/{id}/messages/read": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Marks all unread staff messages in a conversation as read.", "produces": [ "application/json" ], "tags": [ "Portal Support" ], "summary": "Mark messages as read", "parameters": [ { "type": "string", "description": "Conversation ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/conversations/{id}/reopen": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Reopens a closed conversation.", "produces": [ "application/json" ], "tags": [ "Portal Support" ], "summary": "Reopen conversation", "parameters": [ { "type": "string", "description": "Conversation ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/feedback": { "post": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Feedback" ], "summary": "Submit feedback", "parameters": [ { "description": "Feedback", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.createFeedbackRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/login-history": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Security" ], "summary": "Login history", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/app.loginHistoryDTO" } } } } ] } } } } }, "/app/v1/me": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Auth" ], "summary": "Get current user", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.appUserDTO" } } } ] } } } } }, "/app/v1/me/profile": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Profile" ], "summary": "Get profile", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.profileDTO" } } } ] } } } } }, "/app/v1/me/stats": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Profile" ], "summary": "Get stats", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.statsDTO" } } } ] } } } } }, "/app/v1/notifications": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Notifications" ], "summary": "List notifications", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/app.notificationDTO" } } } } ] } } } } }, "/app/v1/notifications/read-all": { "patch": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Notifications" ], "summary": "Mark all notifications read", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/notifications/unread-count": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Notifications" ], "summary": "Unread count", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/notifications/{id}/read": { "patch": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Notifications" ], "summary": "Mark notification read", "parameters": [ { "type": "integer", "description": "Notification ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/oauth/consent": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Processes the user's consent decision (approve or deny). Requires account JWT authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "OAuth Portal" ], "summary": "Submit consent decision", "parameters": [ { "description": "Consent decision", "name": "body", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/passkeys": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Passkeys" ], "summary": "List passkeys", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/app.passkeyDTO" } } } } ] } } } } }, "/app/v1/passkeys/register/begin": { "post": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "Portal Passkeys" ], "summary": "Begin passkey registration", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/passkeys/register/finish": { "post": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Passkeys" ], "summary": "Finish passkey registration", "parameters": [ { "type": "string", "description": "Session ID from register/begin", "name": "X-Session-ID", "in": "header" }, { "type": "string", "description": "Session ID from register/begin", "name": "session_id", "in": "query" }, { "type": "string", "description": "Friendly name for the passkey", "name": "X-Passkey-Name", "in": "header" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.passkeyDTO" } } } ] } } } } }, "/app/v1/passkeys/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Passkeys" ], "summary": "Delete passkey", "parameters": [ { "type": "integer", "description": "Passkey ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "tags": [ "Portal Passkeys" ], "summary": "Rename passkey", "parameters": [ { "type": "integer", "description": "Passkey ID", "name": "id", "in": "path", "required": true }, { "description": "New name", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.updatePasskeyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/profile": { "patch": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "tags": [ "Portal Profile" ], "summary": "Update profile", "parameters": [ { "description": "Profile fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.updateProfileRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.profileDTO" } } } ] } } } } }, "/app/v1/sessions": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Security" ], "summary": "List sessions", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/app.sessionDTO" } } } } ] } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Security" ], "summary": "Revoke all other sessions", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/sessions/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Security" ], "summary": "Revoke session", "parameters": [ { "type": "integer", "description": "Session ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/settings": { "get": { "security": [ { "BearerAuth": [] } ], "tags": [ "Portal Settings" ], "summary": "Get settings", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.settingsDTO" } } } ] } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "tags": [ "Portal Settings" ], "summary": "Update settings", "parameters": [ { "description": "Settings to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.updateSettingsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/app.settingsDTO" } } } ] } } } } }, "/app/v1/social-accounts": { "get": { "security": [ { "AccountJWT": [] } ], "tags": [ "Portal Social" ], "summary": "List linked social accounts", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/social-accounts/{provider}": { "delete": { "security": [ { "AccountJWT": [] } ], "tags": [ "Portal Social" ], "summary": "Unlink social account", "parameters": [ { "type": "string", "description": "Provider to unlink", "name": "provider", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/app/v1/verify/complete": { "post": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Portal Verify" ], "summary": "Complete verification", "parameters": [ { "description": "Session ID", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/app.completeVerificationRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/services.VerificationResult" } } } ] } } } } }, "/dashboard/v1/analytics/breakdown": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns verification data grouped by event type or API key.", "produces": [ "application/json" ], "tags": [ "Dashboard Analytics" ], "summary": "Get analytics breakdown", "parameters": [ { "type": "string", "default": "30 days ago", "description": "Start date (YYYY-MM-DD)", "name": "from", "in": "query" }, { "type": "string", "default": "today", "description": "End date (YYYY-MM-DD)", "name": "to", "in": "query" }, { "type": "string", "default": "type", "description": "Group by: type, api_key", "name": "group_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/analytics/overview": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns aggregated verification stats with previous period comparison.", "produces": [ "application/json" ], "tags": [ "Dashboard Analytics" ], "summary": "Get analytics overview", "parameters": [ { "type": "string", "default": "30 days ago", "description": "Start date (YYYY-MM-DD)", "name": "from", "in": "query" }, { "type": "string", "default": "today", "description": "End date (YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/analytics/timeseries": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns time-bucketed verification data for charts.", "produces": [ "application/json" ], "tags": [ "Dashboard Analytics" ], "summary": "Get analytics timeseries", "parameters": [ { "type": "string", "default": "30 days ago", "description": "Start date (YYYY-MM-DD)", "name": "from", "in": "query" }, { "type": "string", "default": "today", "description": "End date (YYYY-MM-DD)", "name": "to", "in": "query" }, { "type": "string", "default": "day", "description": "Time bucket size: day, week, month", "name": "granularity", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/audit": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated audit logs for the authenticated tenant. Supports filtering by member and action.", "produces": [ "application/json" ], "tags": [ "Dashboard Audit" ], "summary": "List audit logs", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "integer", "description": "Filter by member ID", "name": "member_id", "in": "query" }, { "type": "string", "description": "Filter by action type", "name": "action", "in": "query" }, { "type": "string", "description": "Filter from date (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "Filter to date (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/audit/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a single audit log entry by ID, scoped to the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Audit" ], "summary": "Get audit log entry", "parameters": [ { "type": "integer", "description": "Audit log ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/forgot-password": { "post": { "description": "Send a password reset email. Always returns 200 to prevent email enumeration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Auth" ], "summary": "Request password reset", "parameters": [ { "description": "Email address", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.forgotPasswordRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/login": { "post": { "description": "Authenticate with email and password. Returns JWT access and refresh tokens.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Auth" ], "summary": "Login to dashboard", "parameters": [ { "description": "Login credentials", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.loginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dashboard.loginResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/logout": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Invalidate the current session. Client should discard tokens.", "produces": [ "application/json" ], "tags": [ "Dashboard Auth" ], "summary": "Logout from dashboard", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/logout-all": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Invalidate all active sessions for this user. Stores a revocation timestamp in Redis;", "produces": [ "application/json" ], "tags": [ "Dashboard Auth" ], "summary": "Logout from all devices", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/me": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the authenticated user's profile information.", "produces": [ "application/json" ], "tags": [ "Dashboard Auth" ], "summary": "Get current user", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dashboard.userDTO" } } } ] } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/passkey/authenticate/begin": { "post": { "description": "Starts WebAuthn authentication ceremony. Optionally accepts email for non-discoverable flow.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Passkeys" ], "summary": "Begin passkey authentication", "parameters": [ { "description": "Optional email for non-discoverable flow", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/dashboard.memberAuthBeginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/passkey/authenticate/finish": { "post": { "description": "Completes WebAuthn authentication ceremony. Returns JWT tokens on success.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Passkeys" ], "summary": "Finish passkey authentication", "parameters": [ { "type": "string", "description": "Authentication session ID", "name": "X-Session-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dashboard.loginResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/passkey/register/begin": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Starts WebAuthn registration ceremony. Returns credential creation options and a session ID.", "produces": [ "application/json" ], "tags": [ "Dashboard Passkeys" ], "summary": "Begin passkey registration", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/passkey/register/finish": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Completes WebAuthn registration ceremony. Requires session ID from begin step.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Passkeys" ], "summary": "Finish passkey registration", "parameters": [ { "type": "string", "description": "Registration session ID", "name": "X-Session-ID", "in": "header", "required": true }, { "type": "string", "description": "Passkey display name", "name": "X-Passkey-Name", "in": "header" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dashboard.memberPasskeyDTO" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/passkeys": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all registered passkeys for the authenticated user.", "produces": [ "application/json" ], "tags": [ "Dashboard Passkeys" ], "summary": "List passkeys", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/dashboard.memberPasskeyDTO" } } } } ] } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/passkeys/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Remove a registered passkey from the authenticated user's account.", "produces": [ "application/json" ], "tags": [ "Dashboard Passkeys" ], "summary": "Delete passkey", "parameters": [ { "type": "integer", "description": "Passkey ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Rename a registered passkey.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Passkeys" ], "summary": "Update passkey name", "parameters": [ { "type": "integer", "description": "Passkey ID", "name": "id", "in": "path", "required": true }, { "description": "New passkey name", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.updateMemberPasskeyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/refresh": { "post": { "description": "Exchange a valid refresh token for a new access token.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Auth" ], "summary": "Refresh access token", "parameters": [ { "description": "Refresh token", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.refreshRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/register": { "post": { "description": "Create a new tenant and owner account. Returns a success message.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Auth" ], "summary": "Register a new dashboard account", "parameters": [ { "description": "Registration data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.registerRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/resend-verification": { "post": { "description": "Generates a new verification token and sends a new verification email.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Auth" ], "summary": "Resend verification email", "parameters": [ { "description": "Email address", "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "email": { "type": "string" } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/reset-password": { "post": { "description": "Validate the reset token and set a new password.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Auth" ], "summary": "Reset password with token", "parameters": [ { "description": "Reset token and new password", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.resetPasswordRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/auth/verify-email": { "post": { "description": "Validates the email verification token and activates the member's email.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Auth" ], "summary": "Verify dashboard email", "parameters": [ { "description": "Verification token", "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "token": { "type": "string" } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/billing/active-discounts": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all active free-event quotas and percentage discounts for the tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Billing" ], "summary": "Get active coupon discounts", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/billing/checkout": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a Stripe checkout session for the specified plan. Returns checkout URL.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Billing" ], "summary": "Create Stripe checkout session", "parameters": [ { "description": "Plan selection", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.checkoutRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/billing/credits": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the tenant's current credit balance and recent ledger entries.", "produces": [ "application/json" ], "tags": [ "Dashboard Billing" ], "summary": "Get credit balance and history", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/billing/invoices": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated list of invoices for the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Billing" ], "summary": "List invoices", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/billing/plan": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Upgrades or downgrades the tenant's plan. Requires a payment method on file (via checkout first).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Billing" ], "summary": "Change billing plan", "parameters": [ { "description": "Target plan", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.changePlanRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/billing/plans": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all plan tiers (EUR rates + included volumes) — the single source of truth for the upgrade UI.", "produces": [ "application/json" ], "tags": [ "Dashboard Billing" ], "summary": "Get the plan catalog", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/billing/portal": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a Stripe customer portal session for managing subscriptions and payment methods.", "produces": [ "application/json" ], "tags": [ "Dashboard Billing" ], "summary": "Create Stripe customer portal session", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/billing/redeem-promo": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Redeem a promotional code to receive verification credits.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Billing" ], "summary": "Redeem a promo code", "parameters": [ { "description": "Promo code", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.redeemPromoRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/billing/status": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the current billing status for the authenticated tenant, including plan and subscription details.", "produces": [ "application/json" ], "tags": [ "Dashboard Billing" ], "summary": "Get billing status", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/billing/usage": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns verification usage breakdown for the current billing period.", "produces": [ "application/json" ], "tags": [ "Dashboard Billing" ], "summary": "Get usage breakdown", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/branding": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get the current branding/customization settings for the tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Branding" ], "summary": "Get branding settings", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update the branding/customization settings for the tenant.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Branding" ], "summary": "Update branding settings", "parameters": [ { "description": "Branding settings", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.BrandingSettings" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/branding/logo": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Generate a presigned S3 URL for uploading a tenant logo.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Branding" ], "summary": "Get presigned URL for logo upload", "parameters": [ { "description": "Logo upload metadata", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.logoPresignRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/content-categories": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all active content categories for the dashboard dropdown (project creation/editing).", "produces": [ "application/json" ], "tags": [ "Dashboard Content Rules" ], "summary": "List content categories", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/content-rules": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all country-specific content rules for a given content category. Used by the dashboard to show site owners what min_age applies per country.", "produces": [ "application/json" ], "tags": [ "Dashboard Content Rules" ], "summary": "List content rules by category", "parameters": [ { "type": "string", "description": "Content category (adult, gambling, alcohol, tobacco, social_media, cannabis)", "name": "category", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/dpa/accept": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Record the tenant's acceptance of the current DPA version with signatory details.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard DPA" ], "summary": "Accept DPA", "parameters": [ { "description": "Signatory information", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.AcceptDPARequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/dpa/status": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Check whether the tenant has accepted the current DPA version.", "produces": [ "application/json" ], "tags": [ "Dashboard DPA" ], "summary": "Get DPA status", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/notifications": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List notifications visible to the current member with read status.", "produces": [ "application/json" ], "tags": [ "Dashboard Notifications" ], "summary": "List notifications", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/notifications/unread-count": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the number of unread notifications for the current member.", "produces": [ "application/json" ], "tags": [ "Dashboard Notifications" ], "summary": "Get unread notification count", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/notifications/{id}/read": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Mark a specific notification as read for the current member.", "produces": [ "application/json" ], "tags": [ "Dashboard Notifications" ], "summary": "Mark notification as read", "parameters": [ { "type": "integer", "description": "Notification ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/oauth/clients": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all OAuth clients for the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard OAuth" ], "summary": "List OAuth clients", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new OAuth client for the authenticated tenant. Returns the client and its secret (shown only once).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard OAuth" ], "summary": "Create an OAuth client", "parameters": [ { "description": "OAuth client creation request", "name": "body", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/oauth/clients/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a specific OAuth client by ID, scoped to the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard OAuth" ], "summary": "Get an OAuth client", "parameters": [ { "type": "string", "description": "OAuth client ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Updates an OAuth client's metadata (name, description, logo, redirect URIs, scopes, token TTL).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard OAuth" ], "summary": "Update an OAuth client", "parameters": [ { "type": "string", "description": "OAuth client ID", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently deletes an OAuth client and all associated tokens.", "produces": [ "application/json" ], "tags": [ "Dashboard OAuth" ], "summary": "Delete an OAuth client", "parameters": [ { "type": "string", "description": "OAuth client ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/oauth/clients/{id}/rotate-secret": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Generates a new client secret for the specified OAuth client. The new secret is returned only once.", "produces": [ "application/json" ], "tags": [ "Dashboard OAuth" ], "summary": "Rotate client secret", "parameters": [ { "type": "string", "description": "OAuth client ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/oauth/clients/{id}/stats": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns usage statistics for a specific OAuth client.", "produces": [ "application/json" ], "tags": [ "Dashboard OAuth" ], "summary": "Get OAuth client stats", "parameters": [ { "type": "string", "description": "OAuth client ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/permissions": { "get": { "security": [ { "DashboardBearerAuth": [] } ], "description": "Returns all dashboard permissions organized by resource group", "produces": [ "application/json" ], "tags": [ "Dashboard Roles" ], "summary": "List all dashboard permissions", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/permissions.DashboardPermissionGroup" } } } } ] } } } } }, "/dashboard/v1/projects": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all projects belonging to the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "List projects", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new project under the authenticated tenant. Returns the project with its API key.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Create a new project", "parameters": [ { "description": "Project details", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.CreateProjectRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/projects/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a single project by its ID, scoped to the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Get project by ID", "parameters": [ { "type": "integer", "description": "Project ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently deletes a project and its associated API keys.", "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Delete a project", "parameters": [ { "type": "integer", "description": "Project ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Updates project settings such as name, domains, and configuration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Update a project", "parameters": [ { "type": "integer", "description": "Project ID", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.UpdateProjectRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/projects/{id}/allowed-countries": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the ISO-3166-1 alpha-2 codes (lowercase) accepted as document-issuer countries. Empty array = no restriction.", "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Get the project's issuer-country allowlist", "parameters": [ { "type": "integer", "description": "Project ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Atomically replaces the allowlist with the provided codes. Empty array = no restriction.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Replace the project's issuer-country allowlist", "parameters": [ { "type": "integer", "description": "Project ID", "name": "id", "in": "path", "required": true }, { "description": "Codes to allow", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.SetAllowedCountriesRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/projects/{id}/logo": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Generate a presigned S3 URL for uploading a project logo. The logo appears on the verify widget's welcome screen.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Get presigned URL for project logo upload", "parameters": [ { "type": "integer", "description": "Project ID", "name": "id", "in": "path", "required": true }, { "description": "Logo upload metadata", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.projectLogoPresignRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/projects/{id}/logs": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated verification session logs for a project. Supports filtering by status.", "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Get project verification logs", "parameters": [ { "type": "integer", "description": "Project ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Filter from date (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "Filter to date (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/projects/{id}/rotate-secret": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Generates a new private key for the project. The old key is immediately invalidated.", "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Rotate project secret key", "parameters": [ { "type": "integer", "description": "Project ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/projects/{id}/webhooks": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the webhook URL configured for a project.", "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Get project webhook URL", "parameters": [ { "type": "integer", "description": "Project ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Saves a single webhook URL for a project. All events are delivered to this URL.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Projects" ], "summary": "Save project webhook URL", "parameters": [ { "type": "integer", "description": "Project ID", "name": "id", "in": "path", "required": true }, { "description": "Webhook URL", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.saveWebhookRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/reviews": { "get": { "security": [ { "DashboardJWT": [] } ], "description": "Returns paginated review items for the authenticated tenant. Supports filtering by status and priority.", "produces": [ "application/json" ], "tags": [ "Dashboard Reviews" ], "summary": "List tenant review queue", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page (max 100)", "name": "per_page", "in": "query" }, { "enum": [ "pending", "in_progress", "approved", "rejected" ], "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "enum": [ "low", "normal", "high" ], "type": "string", "description": "Filter by priority", "name": "priority", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dashboard.ReviewListResponseDTO" } } } ] } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/reviews/stats": { "get": { "security": [ { "DashboardJWT": [] } ], "description": "Returns aggregate counts for the review queue scoped to the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Reviews" ], "summary": "Review queue stats", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dashboard.ReviewStatsDTO" } } } ] } } } } }, "/dashboard/v1/reviews/{id}": { "get": { "security": [ { "DashboardJWT": [] } ], "description": "Returns full review item including the frozen evidence snapshot used for the decision.", "produces": [ "application/json" ], "tags": [ "Dashboard Reviews" ], "summary": "Get review item detail", "parameters": [ { "type": "integer", "description": "Review item ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dashboard.ReviewDetailDTO" } } } ] } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/reviews/{id}/resolve": { "post": { "security": [ { "DashboardJWT": [] } ], "description": "Approves or rejects a pending review. On reject, caller must supply reject_mode=retry (widget offers retake) or reject_mode=final (terminal).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Reviews" ], "summary": "Resolve a review item", "parameters": [ { "type": "integer", "description": "Review item ID", "name": "id", "in": "path", "required": true }, { "description": "Decision payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.ResolveRequestDTO" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/roles": { "get": { "security": [ { "DashboardBearerAuth": [] } ], "description": "Returns the 3 fixed dashboard roles (owner, admin, member)", "produces": [ "application/json" ], "tags": [ "Dashboard Roles" ], "summary": "List dashboard roles", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/dashboard.roleDTO" } } } } ] } } } } }, "/dashboard/v1/rules": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all available verification rules that can be assigned to projects.", "produces": [ "application/json" ], "tags": [ "Dashboard Rules" ], "summary": "List verification rules", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/settings": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the current tenant's settings including name, slug, email, plan tier, and status.", "produces": [ "application/json" ], "tags": [ "Dashboard Settings" ], "summary": "Get tenant settings", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Updates tenant settings such as name, email, and billing email.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Settings" ], "summary": "Update tenant settings", "parameters": [ { "description": "Settings to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.UpdateTenantRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/settings/team": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all team members belonging to the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Settings" ], "summary": "List team members", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Sends an invitation to a new team member by email. Creates an inactive user account.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Settings" ], "summary": "Invite a team member", "parameters": [ { "description": "Invitation details", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/services.InviteMemberRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/settings/team/{userId}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Removes a team member from the tenant. Cannot remove the owner or yourself.", "produces": [ "application/json" ], "tags": [ "Dashboard Settings" ], "summary": "Remove a team member", "parameters": [ { "type": "integer", "description": "User ID", "name": "userId", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Changes the role of a team member. Cannot modify the tenant owner or your own role.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Settings" ], "summary": "Update team member role", "parameters": [ { "type": "integer", "description": "User ID", "name": "userId", "in": "path", "required": true }, { "description": "New role", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.updateRoleRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/settings/team/{userId}/resend": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Resends the invitation email to a pending team member.", "produces": [ "application/json" ], "tags": [ "Dashboard Settings" ], "summary": "Resend team member invitation", "parameters": [ { "type": "integer", "description": "User ID", "name": "userId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/support/stats": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns aggregated support ticket statistics for the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Support" ], "summary": "Get support ticket statistics", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/support/tickets": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated support tickets for the authenticated tenant. Supports filtering by status.", "produces": [ "application/json" ], "tags": [ "Dashboard Support" ], "summary": "List support tickets", "parameters": [ { "type": "string", "description": "Filter by ticket status", "name": "status", "in": "query" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Filter from date (YYYY-MM-DD)", "name": "start_date", "in": "query" }, { "type": "string", "description": "Filter to date (YYYY-MM-DD)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new support ticket with subject, message, category, priority, and optional attachments.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Support" ], "summary": "Create a support ticket", "parameters": [ { "description": "Ticket details", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.createTicketRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/support/tickets/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a single support ticket with its messages, scoped to the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Support" ], "summary": "Get support ticket", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/support/tickets/{id}/attachments/presign": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Generates a presigned S3 URL for uploading a file attachment to a support ticket.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Support" ], "summary": "Get presigned upload URL for ticket attachment", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true }, { "description": "File metadata", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.presignAttachmentRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/dashboard.presignAttachmentResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/support/tickets/{id}/close": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Closes an open support ticket. No further replies can be added until reopened.", "produces": [ "application/json" ], "tags": [ "Dashboard Support" ], "summary": "Close a support ticket", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/support/tickets/{id}/messages/read": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Marks all unread customer messages in a ticket as read by dashboard user.", "produces": [ "application/json" ], "tags": [ "Dashboard Support" ], "summary": "Mark messages as read", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/support/tickets/{id}/reopen": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Reopens a previously closed support ticket.", "produces": [ "application/json" ], "tags": [ "Dashboard Support" ], "summary": "Reopen a support ticket", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/support/tickets/{id}/reply": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Adds a reply message to an existing support ticket. Cannot reply to closed tickets.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Support" ], "summary": "Reply to a support ticket", "parameters": [ { "type": "string", "description": "Ticket ID", "name": "id", "in": "path", "required": true }, { "description": "Reply message", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.replyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/webhook-deliveries": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated delivery log for all webhooks belonging to the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "List all webhook deliveries", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/webhook-deliveries/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a single delivery record with full request/response details.", "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "Get delivery detail", "parameters": [ { "type": "integer", "description": "Delivery ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/webhooks": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns all webhooks for the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "List webhooks", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new webhook endpoint. Returns the signing secret (shown only once).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "Create webhook", "parameters": [ { "description": "Webhook configuration", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.createWebhookRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/webhooks/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns webhook details with recent delivery log.", "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "Get webhook", "parameters": [ { "type": "integer", "description": "Webhook ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft-deletes a webhook.", "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "Delete webhook", "parameters": [ { "type": "integer", "description": "Webhook ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Updates webhook URL, events, or active status.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "Update webhook", "parameters": [ { "type": "integer", "description": "Webhook ID", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dashboard.updateWebhookRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/webhooks/{id}/deliveries": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns paginated delivery log for a webhook.", "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "List webhook deliveries", "parameters": [ { "type": "integer", "description": "Webhook ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/webhooks/{id}/deliveries/{did}/resend": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Re-enqueues a specific delivery for retry.", "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "Resend a delivery", "parameters": [ { "type": "integer", "description": "Webhook ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "description": "Delivery ID", "name": "did", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/webhooks/{id}/rotate-secret": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Generates a new signing secret. Returns the new secret (shown only once).", "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "Rotate webhook secret", "parameters": [ { "type": "integer", "description": "Webhook ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/dashboard/v1/webhooks/{id}/test": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Sends a test event to the webhook endpoint.", "produces": [ "application/json" ], "tags": [ "Dashboard Webhooks" ], "summary": "Test webhook", "parameters": [ { "type": "integer", "description": "Webhook ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/health": { "get": { "description": "Returns the basic health status of the API server including uptime and version.", "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Basic health check", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handlers.HealthResponse" } } } } }, "/health/db": { "get": { "description": "Returns the overall health status of the API server. Reports only ok/error to avoid leaking infrastructure details.", "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Health check with database status", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handlers.HealthResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/handlers.HealthResponse" } } } } }, "/health/ready": { "get": { "description": "Returns 200 when the process has completed all startup tasks (model sync, DB migrations) and is ready to serve traffic. Returns 503 until ready. Load balancers and orchestrators should gate traffic on this.", "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Readiness probe", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handlers.HealthResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/handlers.HealthResponse" } } } } }, "/oauth/authorize": { "get": { "description": "Validates parameters, checks for existing consent, creates a Redis session, and redirects to the portal consent screen.", "tags": [ "OAuth" ], "summary": "Start OAuth authorization flow", "parameters": [ { "type": "string", "description": "OAuth response type (code)", "name": "response_type", "in": "query", "required": true }, { "type": "string", "description": "OAuth client ID", "name": "client_id", "in": "query", "required": true }, { "type": "string", "description": "Redirect URI after authorization", "name": "redirect_uri", "in": "query", "required": true }, { "type": "string", "description": "Requested scopes (space-separated)", "name": "scope", "in": "query" }, { "type": "string", "description": "Opaque state value for CSRF protection", "name": "state", "in": "query" }, { "type": "string", "description": "Nonce for ID token replay protection", "name": "nonce", "in": "query" }, { "type": "string", "description": "PKCE code challenge", "name": "code_challenge", "in": "query" }, { "type": "string", "description": "PKCE method (S256)", "name": "code_challenge_method", "in": "query" } ], "responses": { "302": { "description": "Redirect to consent screen" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/oauth/consent/info": { "get": { "description": "Returns consent session data (client name, logo, scopes, redirect URI) for the portal consent screen.", "produces": [ "application/json" ], "tags": [ "OAuth" ], "summary": "Get consent session info", "parameters": [ { "type": "string", "description": "Consent session ID", "name": "session", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/oauth/introspect": { "post": { "description": "Returns token metadata per RFC 7662. Requires client authentication. Returns active/inactive status.", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "tags": [ "OAuth" ], "summary": "Introspect an OAuth token", "parameters": [ { "type": "string", "description": "Token to introspect", "name": "token", "in": "formData", "required": true }, { "type": "string", "description": "Client ID (for client_secret_post auth)", "name": "client_id", "in": "formData" }, { "type": "string", "description": "Client secret (for client_secret_post auth)", "name": "client_secret", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/oauth/revoke": { "post": { "description": "Revokes an access or refresh token per RFC 7009. Requires client authentication. Always returns 200 for valid clients regardless of token validity.", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "tags": [ "OAuth" ], "summary": "Revoke an OAuth token", "parameters": [ { "type": "string", "description": "Token to revoke", "name": "token", "in": "formData", "required": true }, { "type": "string", "description": "Token type hint (access_token or refresh_token)", "name": "token_type_hint", "in": "formData" }, { "type": "string", "description": "Client ID (for client_secret_post auth)", "name": "client_id", "in": "formData" }, { "type": "string", "description": "Client secret (for client_secret_post auth)", "name": "client_secret", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/oauth/token": { "post": { "description": "Supports grant_type=authorization_code and grant_type=refresh_token. Authenticates client via client_secret_post or client_secret_basic.", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "tags": [ "OAuth" ], "summary": "Exchange authorization code or refresh token", "parameters": [ { "type": "string", "description": "Grant type (authorization_code or refresh_token)", "name": "grant_type", "in": "formData", "required": true }, { "type": "string", "description": "Authorization code (required for authorization_code grant)", "name": "code", "in": "formData" }, { "type": "string", "description": "Redirect URI (must match original request)", "name": "redirect_uri", "in": "formData" }, { "type": "string", "description": "Client ID (for client_secret_post auth)", "name": "client_id", "in": "formData" }, { "type": "string", "description": "Client secret (for client_secret_post auth)", "name": "client_secret", "in": "formData" }, { "type": "string", "description": "PKCE code verifier", "name": "code_verifier", "in": "formData" }, { "type": "string", "description": "Refresh token (required for refresh_token grant)", "name": "refresh_token", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/oauth/userinfo": { "get": { "security": [ { "OAuthBearerAuth": [] } ], "description": "Returns user claims based on the scopes granted to the access token. Requires a valid OAuth access token.", "produces": [ "application/json" ], "tags": [ "OAuth" ], "summary": "Get OIDC user info", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/public/v1/careers/apply": { "post": { "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "Public" ], "summary": "Submit a career application", "parameters": [ { "type": "string", "description": "First name", "name": "firstName", "in": "formData", "required": true }, { "type": "string", "description": "Last name", "name": "lastName", "in": "formData", "required": true }, { "type": "string", "description": "Email address", "name": "email", "in": "formData", "required": true }, { "type": "string", "description": "Phone number", "name": "phone", "in": "formData" }, { "type": "string", "description": "Current location", "name": "location", "in": "formData", "required": true }, { "type": "string", "description": "Position of interest", "name": "position", "in": "formData", "required": true }, { "type": "string", "description": "Years of experience", "name": "experience", "in": "formData", "required": true }, { "type": "string", "description": "LinkedIn profile URL", "name": "linkedin", "in": "formData" }, { "type": "string", "description": "Portfolio or GitHub URL", "name": "portfolio", "in": "formData" }, { "type": "string", "description": "Cover message", "name": "message", "in": "formData" }, { "type": "file", "description": "Resume/CV file (PDF, DOC, DOCX — max 10MB)", "name": "cv", "in": "formData", "required": true }, { "type": "file", "description": "Cover letter file (PDF, DOC, DOCX — max 10MB)", "name": "coverLetter", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/public/v1/contact": { "post": { "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "Public" ], "summary": "Submit a contact form", "parameters": [ { "type": "string", "description": "First name", "name": "firstName", "in": "formData", "required": true }, { "type": "string", "description": "Last name", "name": "lastName", "in": "formData", "required": true }, { "type": "string", "description": "Email address", "name": "email", "in": "formData", "required": true }, { "type": "string", "description": "Company name", "name": "company", "in": "formData" }, { "type": "string", "description": "Contact reason", "name": "reason", "in": "formData" }, { "type": "string", "description": "Message", "name": "message", "in": "formData", "required": true }, { "type": "string", "description": "Turnstile verification token", "name": "cf-turnstile-response", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/public/v1/status": { "get": { "description": "Returns the operational status of all backend services.", "produces": [ "application/json" ], "tags": [ "Public" ], "summary": "Get system status", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handlers.PublicStatusResponse" } } } } }, "/public/v1/surveys/{slug}": { "get": { "description": "Returns the survey schema for rendering. Only active surveys are returned.", "produces": [ "application/json" ], "tags": [ "Public" ], "summary": "Get survey schema", "parameters": [ { "type": "string", "description": "Survey slug", "name": "slug", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/public/v1/surveys/{slug}/responses": { "post": { "description": "Submit answers for a survey. Requires Turnstile verification.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Public" ], "summary": "Submit survey response", "parameters": [ { "type": "string", "description": "Survey slug", "name": "slug", "in": "path", "required": true }, { "description": "Survey response", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handlers.surveySubmitRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/public/v1/versions": { "get": { "description": "Returns the version strings for all Xident applications.", "produces": [ "application/json" ], "tags": [ "Public" ], "summary": "Get application versions", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handlers.VersionsResponse" } } } } }, "/public/v1/waitlist": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Public" ], "summary": "Subscribe to waitlist", "parameters": [ { "description": "Waitlist subscription", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handlers.waitlistSubscribeRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/2fa/challenge": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new face-based 2FA challenge. Returns a challenge ID that must be used with the verify endpoint.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK 2FA" ], "summary": "Create face 2FA challenge", "parameters": [ { "description": "Challenge request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.createChallengeRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/2fa/status/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Check the status of a face 2FA challenge.", "produces": [ "application/json" ], "tags": [ "SDK 2FA" ], "summary": "Get face 2FA challenge status", "parameters": [ { "type": "string", "description": "Challenge ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/2fa/verify": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Face 2FA verification requires server-side biometric processing which is not yet enabled. Client-asserted liveness/matching results are not accepted.", "produces": [ "application/json" ], "tags": [ "SDK 2FA" ], "summary": "Verify face 2FA challenge (not yet available)", "responses": { "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/connections": { "get": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Returns an empty list — account_connections table dropped for ARCOM compliance.", "produces": [ "application/json" ], "tags": [ "Accounts" ], "summary": "List connected sites", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/verify.connectionDTO" } } } } ] } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/login": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Authenticate an end user with email and password. Returns JWT access/refresh tokens and account info. Optionally checks if the user has a verified age bracket \u003e= min_age.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Accounts" ], "summary": "Login to Xident account", "parameters": [ { "description": "Login credentials", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.accountLoginRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.accountLoginResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/me": { "get": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Returns the authenticated account's profile information and verified age brackets. Requires account JWT via X-Account-Token header.", "produces": [ "application/json" ], "tags": [ "Accounts" ], "summary": "Get current account profile", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "delete": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Permanently deletes the authenticated account and all associated data including passkeys, verified ages, and site connections. This action cannot be undone. Implements GDPR Art. 17 right to erasure.", "produces": [ "application/json" ], "tags": [ "Accounts" ], "summary": "Delete Xident account", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/passkey/authenticate/begin": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Starts a discoverable credential (WebAuthn) ceremony for conditional UI or hybrid passkey login. Returns assertion options and a session ID for the finish step.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Account Passkeys" ], "summary": "Begin passkey authentication", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/passkey/authenticate/finish": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Completes the discoverable credential ceremony by validating the authenticator response. Returns JWT access/refresh tokens on success. Session ID must be passed via X-Session-ID header or session_id query parameter.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Account Passkeys" ], "summary": "Finish passkey authentication", "parameters": [ { "type": "string", "description": "Session ID from authenticate/begin (alternative to query param)", "name": "X-Session-ID", "in": "header" }, { "type": "string", "description": "Session ID from authenticate/begin (alternative to header)", "name": "session_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.accountLoginResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/passkey/register/begin": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Starts a WebAuthn credential creation ceremony for the authenticated account. Returns creation options and a session ID for the finish step. Requires account JWT via X-Account-Token header.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Account Passkeys" ], "summary": "Begin passkey registration", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/passkey/register/finish": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Completes the WebAuthn credential creation ceremony by validating the authenticator response and storing the new passkey. Session ID via X-Session-ID header or session_id query param. Optional X-Passkey-Name header to name the passkey. Requires account JWT via X-Account-Token header.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Account Passkeys" ], "summary": "Finish passkey registration", "parameters": [ { "type": "string", "description": "Session ID from register/begin (alternative to query param)", "name": "X-Session-ID", "in": "header" }, { "type": "string", "description": "Session ID from register/begin (alternative to header)", "name": "session_id", "in": "query" }, { "type": "string", "description": "Friendly name for the passkey (default: My Passkey)", "name": "X-Passkey-Name", "in": "header" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.accountPasskeyDTO" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/passkeys": { "get": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Returns all registered passkeys for the authenticated account, including platform, browser, sign count, and last-used timestamps. Requires account JWT via X-Account-Token header.", "produces": [ "application/json" ], "tags": [ "Account Passkeys" ], "summary": "List account passkeys", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/verify.accountPasskeyDTO" } } } } ] } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/passkeys/{id}": { "delete": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Removes a registered passkey from the authenticated account. The passkey must belong to the account. Requires account JWT via X-Account-Token header.", "produces": [ "application/json" ], "tags": [ "Account Passkeys" ], "summary": "Delete a passkey", "parameters": [ { "type": "integer", "description": "Passkey ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/quick-register": { "post": { "security": [ { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Accounts" ], "summary": "Quick register (email only)", "parameters": [ { "description": "Quick register", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.quickRegisterRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/accounts/register": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Create a new Xident account with email and optional password. If session_id is provided, links the verification session to the new account. Returns JWT tokens.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Accounts" ], "summary": "Register a new Xident account", "parameters": [ { "description": "Registration details", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.accountRegisterRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.accountLoginResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/branding": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the tenant's branding customization for the verification widget. Authenticated via API key.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Get branding for verify widget", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/countries": { "get": { "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "List supported countries and doc-type availability for the verify widget", "parameters": [ { "type": "string", "description": "europe | templates | all (default: europe)", "name": "scope", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/events/{type}/{id}/stream": { "get": { "description": "Opens an SSE connection for session or OCR status events", "produces": [ "text/event-stream" ], "tags": [ "events" ], "summary": "Subscribe to real-time events", "parameters": [ { "type": "string", "description": "Event type (session or ocr)", "name": "type", "in": "path", "required": true }, { "type": "string", "description": "Resource ID (session_id or task_id)", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "API key for authentication", "name": "api_key", "in": "query", "required": true } ], "responses": { "200": { "description": "SSE event stream", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/face/enroll": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Queues a face enrollment job for a user. The face image is processed asynchronously by ML workers.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Enroll face for recognition", "parameters": [ { "description": "Face enrollment request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.EnrollRequestDTO" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/face/verify": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Queues a face verification job that compares a face image against the user's enrolled template. Processed asynchronously by ML workers.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Verify face against enrolled template", "parameters": [ { "description": "Face verification request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.VerifyFaceRequestDTO" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/feedback": { "post": { "security": [ { "ApiKeyAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Widget Feedback" ], "summary": "Submit widget feedback", "parameters": [ { "description": "Feedback", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.widgetFeedbackRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/init": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Exchange API key + verification params for a short-lived init token", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Verify Init" ], "summary": "Create init token", "parameters": [ { "description": "Init parameters", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.createInitRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.createInitResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/init/{token}": { "get": { "description": "Exchange a one-time init token for verification config (public — no auth)", "produces": [ "application/json" ], "tags": [ "Verify Init" ], "summary": "Redeem init token", "parameters": [ { "type": "string", "description": "Init token", "name": "token", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/services.InitParams" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/liveness/challenge": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new liveness challenge with random actions the user must perform.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Get liveness challenge", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/liveness/verify": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Submits liveness detection frames for a previously created challenge.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Verify liveness challenge", "parameters": [ { "description": "Liveness verification request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.VerifyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "410": { "description": "Gone", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/ocr/presign": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Generates presigned S3 URLs for uploading document images and selfies for OCR processing.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Get presigned upload URLs for typed files", "parameters": [ { "description": "Presign request with typed files", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.PresignRequestDTO" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/ocr/status/{task_id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the current status of an OCR processing task, including results when complete.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Poll OCR task status", "parameters": [ { "type": "string", "description": "OCR Task ID", "name": "task_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/ocr/verify-urls": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Confirms that documents have been uploaded and queues the OCR processing job. File keys are read from the presign record.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Verify uploaded document URLs and start OCR processing", "parameters": [ { "description": "Verify URLs request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.VerifyURLsRequestDTO" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/optical/upload": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Submits an L5 flash-pair or L6 tilt-sequence capture for OVD analysis. The verdict is stored on the session and folded into the OCR worker's docverify decision. Hard-rejects on capture-proof failure.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Verify Optical" ], "summary": "Upload an optical capture (flash-pair or tilt-sequence)", "parameters": [ { "description": "Optical capture payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.uploadRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.uploadResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "412": { "description": "Precondition Failed", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/requirements": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Determines which verification methods are required using the API key from authentication middleware.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Check verification requirements (authenticated)", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/requirements/check": { "get": { "description": "Determines which verification methods are required based on API key and user location. Accepts API key via X-API-Key header.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Check verification requirements (public)", "parameters": [ { "type": "string", "description": "API Key", "name": "X-API-Key", "in": "header", "required": true }, { "type": "string", "description": "External user ID for retry tracking", "name": "user_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/result/{token}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the current verification status for a session including liveness, age, OCR, and face match results.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Get verification session result", "parameters": [ { "type": "string", "description": "Verification session token", "name": "token", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/review-request": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Submit a failed verification for human review. Requires document uploads.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Widget Review" ], "summary": "Request human review", "parameters": [ { "description": "Review request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.reviewRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/sessions/{id}/age-estimation": { "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Stores client-side age estimation result on the verification session.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Update session with age estimation result", "parameters": [ { "type": "string", "description": "Session ID", "name": "id", "in": "path", "required": true }, { "description": "Age estimation result", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.AgeEstimationResultDTO" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/sessions/{id}/complete": { "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Marks a session as completed or failed. Records usage event and dispatches webhook.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Complete a verification session", "parameters": [ { "type": "string", "description": "Session ID", "name": "id", "in": "path", "required": true }, { "description": "Completion data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.CompleteSessionDTO" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/sessions/{id}/files": { "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Deletes all S3 files associated with a verification session (e.g., when user declines consent).", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Delete session files", "parameters": [ { "type": "string", "description": "Session ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/sessions/{id}/handoff": { "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Called by mobile device when opening a QR handoff URL. Marks the session so the desktop knows mobile has taken over.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Mark session as mobile handoff", "parameters": [ { "type": "string", "description": "Session ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/sessions/{id}/liveness": { "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Stores liveness detection result on the verification session.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Update session with liveness result", "parameters": [ { "type": "string", "description": "Session ID", "name": "id", "in": "path", "required": true }, { "description": "Liveness result", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.LivenessResultDTO" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/sessions/{id}/self-declaration": { "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Stores the user's self-declared age on the verification session.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Store self-declaration on session", "parameters": [ { "type": "string", "description": "Session ID", "name": "id", "in": "path", "required": true }, { "description": "Self-declaration data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.SelfDeclarationDTO" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/sessions/{token}/capture-key": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Widget calls this once per session to obtain the HMAC key used to sign capture-proof tokens at presign time. Idempotent — subsequent calls return the same key until session expiry.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Issue or fetch a per-session HMAC key for capture-proof signing", "parameters": [ { "type": "string", "description": "Session token (xtk_...)", "name": "token", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.CaptureKeyResponseDTO" } } } ] } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/sessions/{token}/retake": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Called by the widget after a tenant rejects with reject_mode=retry. Returns a new session token linked to the original; widget restarts capture against it. Enforces max 3 retakes per chain.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Create a retake session", "parameters": [ { "type": "string", "description": "Original session token (xtk_...)", "name": "token", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.RetakeResponseDTO" } } } ] } }, "404": { "description": "session not found / wrong tenant", "schema": { "$ref": "#/definitions/response.Envelope" } }, "409": { "description": "session not in awaiting_retake state OR retake limit exceeded", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/telemetry/capture": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Persists gyroscope, ambient light, capture-latency, and page-visibility samples collected by the verify widget for offline behavioral-model training. Pure ingest — no risk-score effect today.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Verify Telemetry" ], "summary": "Submit capture-time telemetry batch", "parameters": [ { "description": "Telemetry payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/telemetry.Payload" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.captureResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/tokens": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns all API keys for the authenticated tenant.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "List API keys", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new API key for the authenticated tenant.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Create API key", "parameters": [ { "description": "API key creation request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.CreateAPIKeyRequestDTO" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/tokens/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a single API key by its ID.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Get API key by ID", "parameters": [ { "type": "integer", "description": "API Key ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Deactivates an API key by its ID. The key is not physically deleted.", "produces": [ "application/json" ], "tags": [ "SDK" ], "summary": "Delete (deactivate) API key", "parameters": [ { "type": "integer", "description": "API Key ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/verification-tokens/issue": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Issues a verification token for the authenticated account's verified age bracket. The embedding site can later use this token to check the user's age without re-verification. Requires account JWT via X-Account-Token header and API key context.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Verification Tokens" ], "summary": "Issue a verification token", "parameters": [ { "description": "Token issue parameters", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.issueTokenRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.issueTokenResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/verification-tokens/revoke": { "post": { "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "description": "Revokes an active verification token so it can no longer be used for age checks. The token must belong to the authenticated account. Requires account JWT via X-Account-Token header.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Verification Tokens" ], "summary": "Revoke a verification token", "parameters": [ { "description": "Token to revoke", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.revokeTokenRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/verification-tokens/verify": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Validates a verification token and returns whether it is valid, the age bracket, verification method, and expiration. Invalid, expired, or revoked tokens return valid=false without error. Requires API key auth.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Verification Tokens" ], "summary": "Verify a verification token", "parameters": [ { "description": "Token to verify", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/verify.verifyTokenRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/response.Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/verify.verifyTokenResponse" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } }, "/verify/v1/wallet/validate": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Receives an mso_mdoc age attestation from a user's EU Digital Identity Wallet,", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Verify Wallet" ], "summary": "Validate EU wallet credential", "parameters": [ { "description": "Wallet credential data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/eudiw.WalletValidateRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/response.Envelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Envelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Envelope" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Envelope" } } } } } }, "definitions": { "admin.addBlacklistRequest": { "type": "object", "required": [ "embedding", "reason", "tenant_id" ], "properties": { "embedding": { "type": "array", "items": { "type": "number" } }, "reason": { "type": "string" }, "tenant_id": { "type": "integer" } } }, "admin.admin2FAChallengeRequest": { "type": "object", "properties": { "challenge_token": { "type": "string" }, "code": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "admin.adminForgotPasswordRequest": { "type": "object", "properties": { "email": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "admin.adminLoginRequest": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "admin.adminLoginResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "challenge_token": { "description": "present only when requires_2fa=true", "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "requires_2fa": { "type": "boolean" }, "user": { "$ref": "#/definitions/admin.adminUserDTO" } } }, "admin.adminRefreshRequest": { "type": "object", "properties": { "refresh_token": { "type": "string" } } }, "admin.adminResetPasswordRequest": { "type": "object", "properties": { "password": { "type": "string" }, "token": { "type": "string" } } }, "admin.adminUserDTO": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "role": { "type": "string" }, "role_id": { "type": "integer" }, "two_factor_enabled": { "type": "boolean" } } }, "admin.announceRequest": { "type": "object", "properties": { "body": { "type": "string" }, "subject": { "type": "string" } } }, "admin.assignReviewRequest": { "type": "object", "properties": { "admin_user_id": { "type": "integer" } } }, "admin.assignRoleRequest": { "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "integer" } } }, "admin.assignTicketRequest": { "type": "object", "properties": { "admin_user_id": { "type": "string" } } }, "admin.attachmentRequestItem": { "type": "object", "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "key": { "type": "string" }, "size": { "type": "integer" } } }, "admin.authBeginRequest": { "type": "object", "properties": { "email": { "type": "string" } } }, "admin.changeStatusRequest": { "type": "object", "properties": { "status": { "type": "string" } } }, "admin.createCategoryRequest": { "type": "object", "required": [ "default_methods", "name", "slug" ], "properties": { "default_methods": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "default_min_age": { "type": "integer", "maximum": 99, "minimum": 0 }, "default_ocr_mandatory": { "type": "boolean" }, "description": { "type": "string" }, "icon": { "type": "string" }, "is_active": { "type": "boolean" }, "name": { "type": "string", "maxLength": 100, "minLength": 2 }, "slug": { "type": "string", "maxLength": 50, "minLength": 2 }, "sort_order": { "type": "integer" } } }, "admin.createCountryRuleRequest": { "type": "object", "required": [ "country_alpha2", "regime" ], "properties": { "challenge_age": { "type": "integer" }, "country_alpha2": { "type": "string", "maxLength": 5, "minLength": 2 }, "law_reference": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" } }, "min_age": { "type": "integer", "maximum": 99, "minimum": 0 }, "notes": { "type": "string" }, "ocr_mandatory": { "type": "boolean" }, "regime": { "type": "string" } } }, "admin.createKnowledgeBaseRequest": { "type": "object" }, "admin.createRoleRequest": { "type": "object", "required": [ "name", "permissions" ], "properties": { "description": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 64, "minLength": 2 }, "permissions": { "type": "array", "minItems": 1, "items": { "type": "string" } } } }, "admin.disable2FARequest": { "type": "object", "properties": { "password": { "type": "string" } } }, "admin.internalNoteRequest": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/definitions/admin.attachmentRequestItem" } }, "message": { "type": "string" } } }, "admin.passkeyDTO": { "type": "object", "properties": { "backup_eligible": { "type": "boolean" }, "backup_state": { "type": "boolean" }, "browser": { "type": "string" }, "created_at": { "type": "string" }, "device_info": { "type": "string" }, "id": { "type": "integer" }, "last_used_at": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" }, "sign_count": { "type": "integer" } } }, "admin.presignAttachmentRequest": { "type": "object", "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" } } }, "admin.presignAttachmentResponse": { "type": "object", "properties": { "expires_at": { "type": "string" }, "key": { "type": "string" }, "public_url": { "type": "string" }, "upload_url": { "type": "string" } } }, "admin.resolveReviewRequest": { "type": "object", "required": [ "status" ], "properties": { "notes": { "type": "string" }, "status": { "type": "string" } } }, "admin.setup2FAResponse": { "type": "object", "properties": { "message": { "type": "string" }, "provisioning_uri": { "type": "string" }, "secret": { "type": "string" } } }, "admin.ticketReplyRequest": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/definitions/admin.attachmentRequestItem" } }, "message": { "type": "string" } } }, "admin.updateKnowledgeBaseRequest": { "type": "object", "properties": { "answer": { "type": "string" }, "category": { "type": "string" }, "is_active": { "type": "boolean" }, "keywords": { "$ref": "#/definitions/models.StringArray" }, "priority": { "type": "integer" }, "question": { "type": "string" } } }, "admin.updatePasskeyRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "admin.updateRoleRequest": { "type": "object", "required": [ "name", "permissions" ], "properties": { "description": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 64, "minLength": 2 }, "permissions": { "type": "array", "minItems": 1, "items": { "type": "string" } } } }, "admin.verify2FARequest": { "type": "object", "properties": { "code": { "type": "string" } } }, "app.activateAccountRequest": { "type": "object", "properties": { "password": { "type": "string" }, "token": { "type": "string" } } }, "app.ageVerificationDTO": { "type": "object", "properties": { "age_bracket": { "type": "integer" }, "confidence": { "type": "number" }, "expires_at": { "type": "string" }, "method": { "type": "string" }, "verified_at": { "type": "string" } } }, "app.appLoginRequest": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "app.appLoginResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "user": { "$ref": "#/definitions/app.appUserDTO" } } }, "app.appRefreshRequest": { "type": "object", "properties": { "refresh_token": { "type": "string" } } }, "app.appRegisterRequest": { "type": "object", "properties": { "display_name": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "app.appUserDTO": { "type": "object", "properties": { "avatar_url": { "type": "string" }, "display_name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "id": { "type": "integer" } } }, "app.completeVerificationRequest": { "type": "object", "properties": { "token": { "type": "string" } } }, "app.connectionDTO": { "type": "object", "properties": { "app_logo": { "type": "string" }, "app_name": { "type": "string" }, "granted_at": { "type": "string" }, "id": { "type": "integer" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "app.createConversationRequest": { "type": "object", "properties": { "category": { "type": "string" }, "message": { "type": "string" }, "subject": { "type": "string" } } }, "app.createFeedbackRequest": { "type": "object", "properties": { "comment": { "type": "string" }, "rating": { "type": "integer" } } }, "app.deleteAccountRequest": { "type": "object", "properties": { "confirmation": { "type": "string" }, "password": { "type": "string" } } }, "app.forgotPasswordRequest": { "type": "object", "properties": { "email": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "app.loginHistoryDTO": { "type": "object", "properties": { "created_at": { "type": "string" }, "failure_reason": { "type": "string" }, "id": { "type": "integer" }, "ip_address": { "type": "string" }, "location": { "type": "string" }, "method": { "type": "string" }, "success": { "type": "boolean" } } }, "app.manualReviewRequest": { "type": "object", "properties": { "reason": { "type": "string" } } }, "app.notificationDTO": { "type": "object", "properties": { "body": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "integer" }, "is_read": { "type": "boolean" }, "title": { "type": "string" }, "type": { "type": "string" } } }, "app.passkeyDTO": { "type": "object", "properties": { "backup_eligible": { "type": "boolean" }, "backup_state": { "type": "boolean" }, "browser": { "type": "string" }, "created_at": { "type": "string" }, "device_info": { "type": "string" }, "id": { "type": "integer" }, "last_used_at": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" }, "sign_count": { "type": "integer" } } }, "app.portalAttachmentRequestItem": { "type": "object", "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "key": { "type": "string" }, "size": { "type": "integer" } } }, "app.portalPresignAttachmentRequest": { "type": "object", "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" } } }, "app.portalPresignAttachmentResponse": { "type": "object", "properties": { "expires_at": { "type": "string" }, "key": { "type": "string" }, "public_url": { "type": "string" }, "upload_url": { "type": "string" } } }, "app.profileDTO": { "type": "object", "properties": { "age_verifications": { "type": "array", "items": { "$ref": "#/definitions/app.ageVerificationDTO" } }, "avatar_url": { "type": "string" }, "bio": { "type": "string" }, "confirmed_dob": { "description": "Gov-ID-only redesign (PR-3): the OCR-extracted DOB and document\nprovenance. ConfirmedDOB is the source of truth for age thresholds —\nthe frontend computes pass/fail from confirmed_dob + today.", "type": "string" }, "created_at": { "type": "string" }, "date_of_birth": { "type": "string" }, "display_name": { "type": "string" }, "dob_confirmed": { "type": "boolean" }, "dob_confirmed_at": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "id": { "type": "integer" }, "id_doc_country": { "type": "string" }, "id_doc_type": { "type": "string" }, "id_verified": { "type": "boolean" }, "id_verified_at": { "type": "string" }, "language": { "type": "string" }, "profile_completeness": { "type": "integer" }, "theme": { "type": "string" } } }, "app.resendVerificationRequest": { "type": "object", "properties": { "email": { "type": "string" } } }, "app.resetPasswordRequest": { "type": "object", "properties": { "password": { "type": "string" }, "token": { "type": "string" } } }, "app.sendMessageRequest": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/definitions/app.portalAttachmentRequestItem" } }, "message": { "type": "string" } } }, "app.sessionDTO": { "type": "object", "properties": { "browser": { "type": "string" }, "created_at": { "type": "string" }, "device_name": { "type": "string" }, "id": { "type": "integer" }, "ip_address": { "type": "string" }, "is_current": { "type": "boolean" }, "last_active_at": { "type": "string" }, "location": { "type": "string" }, "platform": { "type": "string" } } }, "app.settingsDTO": { "type": "object", "properties": { "language": { "type": "string" }, "notification_prefs": { "$ref": "#/definitions/models.JSONMap" }, "theme": { "type": "string" } } }, "app.statsDTO": { "type": "object", "properties": { "passkey_count": { "type": "integer" }, "site_count": { "type": "integer" } } }, "app.updatePasskeyRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "app.updateProfileRequest": { "type": "object", "properties": { "bio": { "type": "string" }, "date_of_birth": { "type": "string" }, "display_name": { "type": "string" } } }, "app.updateSettingsRequest": { "type": "object", "properties": { "language": { "type": "string" }, "notification_prefs": { "$ref": "#/definitions/models.JSONMap" }, "theme": { "type": "string" } } }, "app.verifyEmailRequest": { "type": "object", "properties": { "token": { "type": "string" } } }, "dashboard.AcceptDPARequest": { "type": "object", "properties": { "company_legal_name": { "type": "string" }, "signatory_name": { "type": "string" }, "signatory_title": { "type": "string" } } }, "dashboard.ResolveRequestDTO": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "description": "Decision: \"approved\" or \"rejected\". Validated at the handler.", "type": "string", "enum": [ "approved", "rejected" ] }, "note": { "description": "Note: optional human-readable comment attached to the decision.", "type": "string" }, "reject_mode": { "description": "RejectMode: \"retry\" or \"final\". Required when Decision=rejected,\nmust be empty otherwise.", "type": "string", "enum": [ "retry", "final" ] } } }, "dashboard.ReviewDetailDTO": { "type": "object", "properties": { "created_at": { "type": "string" }, "document_back_key": { "type": "string" }, "document_front_key": { "type": "string" }, "evidence_snapshot": { "type": "object", "additionalProperties": {} }, "flag_source": { "type": "string" }, "id": { "type": "integer" }, "priority": { "type": "string" }, "reason": { "type": "string" }, "reject_mode": { "type": "string" }, "resolved_at": { "type": "string" }, "reviewer_notes": { "type": "string" }, "selfie_key": { "type": "string" }, "session_id": { "type": "integer" }, "status": { "type": "string" } } }, "dashboard.ReviewListItemDTO": { "type": "object", "properties": { "created_at": { "type": "string" }, "flag_source": { "type": "string" }, "id": { "type": "integer" }, "priority": { "type": "string" }, "reason": { "type": "string" }, "reject_mode": { "type": "string" }, "resolved_at": { "type": "string" }, "session_id": { "type": "integer" }, "status": { "type": "string" } } }, "dashboard.ReviewListResponseDTO": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/dashboard.ReviewListItemDTO" } }, "stats": { "$ref": "#/definitions/dashboard.ReviewStatsDTO" }, "total": { "type": "integer" } } }, "dashboard.ReviewStatsDTO": { "type": "object", "properties": { "approved": { "type": "integer" }, "in_progress": { "type": "integer" }, "pending": { "type": "integer" }, "rejected": { "type": "integer" }, "total": { "type": "integer" } } }, "dashboard.SetAllowedCountriesRequest": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" } } } }, "dashboard.attachmentRequestItem": { "type": "object", "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "key": { "type": "string" }, "size": { "type": "integer" } } }, "dashboard.changePlanRequest": { "type": "object", "properties": { "plan": { "type": "string" } } }, "dashboard.checkoutRequest": { "type": "object", "properties": { "plan": { "type": "string" } } }, "dashboard.createTicketRequest": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/definitions/dashboard.attachmentRequestItem" } }, "category": { "type": "string" }, "message": { "type": "string" }, "priority": { "type": "string" }, "subject": { "type": "string" } } }, "dashboard.createWebhookRequest": { "type": "object", "required": [ "api_key_id", "url" ], "properties": { "api_key_id": { "type": "integer" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" } } }, "dashboard.forgotPasswordRequest": { "type": "object", "properties": { "email": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "dashboard.loginRequest": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "dashboard.loginResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "user": { "$ref": "#/definitions/dashboard.userDTO" } } }, "dashboard.logoPresignRequest": { "type": "object", "required": [ "content_type", "filename", "size" ], "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" } } }, "dashboard.memberAuthBeginRequest": { "type": "object", "properties": { "email": { "type": "string" } } }, "dashboard.memberPasskeyDTO": { "type": "object", "properties": { "backup_eligible": { "type": "boolean" }, "backup_state": { "type": "boolean" }, "browser": { "type": "string" }, "created_at": { "type": "string" }, "device_info": { "type": "string" }, "id": { "type": "integer" }, "last_used_at": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" }, "sign_count": { "type": "integer" } } }, "dashboard.presignAttachmentRequest": { "type": "object", "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" } } }, "dashboard.presignAttachmentResponse": { "type": "object", "properties": { "expires_at": { "type": "string" }, "key": { "type": "string" }, "public_url": { "type": "string" }, "upload_url": { "type": "string" } } }, "dashboard.projectLogoPresignRequest": { "type": "object", "required": [ "content_type", "filename", "size" ], "properties": { "content_type": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" } } }, "dashboard.redeemPromoRequest": { "type": "object", "properties": { "code": { "type": "string" } } }, "dashboard.refreshRequest": { "type": "object", "properties": { "refresh_token": { "type": "string" } } }, "dashboard.registerRequest": { "type": "object", "properties": { "company_name": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "dashboard.replyRequest": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/definitions/dashboard.attachmentRequestItem" } }, "message": { "type": "string" } } }, "dashboard.resetPasswordRequest": { "type": "object", "properties": { "password": { "type": "string" }, "token": { "type": "string" } } }, "dashboard.roleDTO": { "type": "object", "properties": { "description": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } } }, "dashboard.saveWebhookRequest": { "type": "object", "properties": { "url": { "type": "string" } } }, "dashboard.updateMemberPasskeyRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "dashboard.updateRoleRequest": { "type": "object", "properties": { "role": { "type": "string" } } }, "dashboard.updateWebhookRequest": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "url": { "type": "string" } } }, "dashboard.userDTO": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "role": { "type": "string" }, "role_id": { "type": "integer" }, "tenant_id": { "type": "integer" } } }, "eudiw.WalletValidateRequest": { "type": "object", "required": [ "credential_data", "nonce", "session_id" ], "properties": { "credential_data": { "description": "Base64url-encoded mso_mdoc", "type": "string" }, "min_age": { "description": "Requested age threshold (default 18)", "type": "integer" }, "nonce": { "type": "string" }, "session_id": { "type": "string" } } }, "handlers.HealthResponse": { "type": "object", "properties": { "status": { "type": "string" }, "timestamp": { "type": "string" }, "uptime": { "type": "string" }, "version": { "type": "string" } } }, "handlers.PublicStatusResponse": { "type": "object", "properties": { "services": { "type": "object", "additionalProperties": { "$ref": "#/definitions/handlers.ServiceStatus" } }, "status": { "type": "string" }, "timestamp": { "type": "string" }, "uptime": { "type": "string" }, "version": { "type": "string" } } }, "handlers.ServiceStatus": { "type": "object", "properties": { "latency_ms": { "type": "integer" }, "status": { "type": "string" } } }, "handlers.VersionsResponse": { "type": "object", "properties": { "admin": { "type": "string" }, "api": { "type": "string" }, "dashboard": { "type": "string" }, "docs": { "type": "string" }, "sdk": { "type": "string" } } }, "handlers.surveySubmitRequest": { "type": "object" }, "handlers.waitlistSubscribeRequest": { "type": "object", "properties": { "email": { "type": "string" }, "turnstile_token": { "type": "string" } } }, "models.BrandingSettings": { "type": "object", "properties": { "background_color": { "type": "string" }, "border_radius": { "type": "string" }, "custom_css": { "type": "string" }, "font_family": { "type": "string" }, "logo_url": { "type": "string" }, "primary_color": { "type": "string" }, "secondary_color": { "type": "string" }, "text_color": { "type": "string" } } }, "models.JSONMap": { "type": "object", "additionalProperties": {} }, "models.StringArray": { "type": "object" }, "optical.FlashPairCapture": { "type": "object", "properties": { "frame_off": { "description": "base64 data URL, JPEG", "type": "string" }, "frame_on": { "description": "base64 data URL, JPEG", "type": "string" }, "height": { "type": "integer" }, "timestamp_off_ms": { "description": "wall-clock ms since epoch", "type": "integer" }, "timestamp_on_ms": { "type": "integer" }, "width": { "type": "integer" } } }, "optical.TiltFrame": { "type": "object", "properties": { "data_url": { "description": "base64 JPEG", "type": "string" }, "offset_ms": { "description": "ms since sequence start", "type": "integer" } } }, "optical.TiltSequenceCapture": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "frames": { "type": "array", "items": { "$ref": "#/definitions/optical.TiltFrame" } }, "height": { "type": "integer" }, "width": { "type": "integer" } } }, "permissions.AdminPermissionGroup": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } } }, "permissions.DashboardPermissionGroup": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } } }, "response.Envelope": { "type": "object", "properties": { "data": {}, "error": { "$ref": "#/definitions/response.Error" }, "meta": { "$ref": "#/definitions/response.Meta" }, "success": { "type": "boolean" } } }, "response.Error": { "type": "object", "properties": { "code": { "type": "string" }, "details": {}, "message": { "type": "string" } } }, "response.Meta": { "type": "object", "properties": { "pagination": { "$ref": "#/definitions/response.Pagination" }, "request_id": { "type": "string" }, "timestamp": { "type": "string" } } }, "response.Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "services.AdminRoleDTO": { "type": "object", "properties": { "created_at": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "permission_count": { "type": "integer" }, "permissions": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string" }, "user_count": { "type": "integer" } } }, "services.CreateNotificationRequest": { "type": "object", "required": [ "body", "recipient_type", "title" ], "properties": { "body": { "type": "string" }, "delivery_channel": { "type": "string" }, "recipient_id": { "type": "integer" }, "recipient_tag": { "type": "string" }, "recipient_type": { "type": "string" }, "title": { "type": "string", "maxLength": 255 } } }, "services.CreateProjectRequest": { "type": "object", "properties": { "allowed_origins": { "type": "string" }, "content_category": { "type": "string" }, "domains": { "type": "string" }, "min_age": { "type": "integer" }, "name": { "type": "string" }, "rule_id": { "type": "integer" } } }, "services.CreatePromoRequest": { "type": "object", "required": [ "code" ], "properties": { "applicable_event_types": { "description": "for free_events type (empty = all)", "type": "array", "items": { "type": "string" } }, "campaign": { "type": "string" }, "channel": { "type": "string" }, "code": { "type": "string", "maxLength": 50, "minLength": 3 }, "credit_cents": { "description": "for credit type", "type": "integer" }, "credit_expires_days": { "type": "integer" }, "description": { "type": "string" }, "discount_type": { "description": "\"credit\" (default), \"free_events\", \"percent\"", "type": "string" }, "duration_months": { "description": "for percent type", "type": "integer" }, "eligible_plans": { "type": "array", "items": { "type": "string" } }, "free_event_count": { "description": "for free_events type", "type": "integer" }, "max_uses": { "type": "integer" }, "percent_discount": { "description": "for percent type (0.01-100.0)", "type": "number" }, "valid_until": { "type": "string" } } }, "services.CreateSurveyRequest": { "type": "object" }, "services.GrantCreditsRequest": { "type": "object", "required": [ "amount_cents", "reason" ], "properties": { "amount_cents": { "type": "integer", "minimum": 1 }, "expires_at": { "type": "string" }, "reason": { "type": "string" } } }, "services.InitParams": { "type": "object", "properties": { "api_key": { "type": "string" }, "callback_url": { "type": "string" }, "failed_url": { "type": "string" }, "liveness_difficulty": { "type": "string" }, "locale": { "type": "string" }, "metadata": { "type": "string" }, "min_age": { "type": "integer" }, "purpose": { "description": "\"age_verification\" (default) or \"id_verification\"", "type": "string" }, "success_url": { "type": "string" }, "theme": { "type": "string" }, "user_id": { "type": "string" } } }, "services.InviteMemberRequest": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } } }, "services.LagoPlanChargeUpdate": { "type": "object", "properties": { "charge_model": { "type": "string" }, "id": { "type": "string" }, "properties": { "type": "object", "properties": { "amount": { "type": "string" }, "free_units": { "type": "string" } } } } }, "services.LagoPlanUpdate": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "charges": { "type": "array", "items": { "$ref": "#/definitions/services.LagoPlanChargeUpdate" } }, "description": { "type": "string" }, "name": { "type": "string" } } }, "services.OnboardRequest": { "type": "object", "required": [ "credit_cents", "tenant_ids" ], "properties": { "credit_cents": { "type": "integer", "minimum": 1 }, "credit_expires_days": { "type": "integer" }, "send_welcome_email": { "type": "boolean" }, "tenant_ids": { "type": "array", "minItems": 1, "items": { "type": "integer" } }, "welcome_body": { "type": "string" }, "welcome_subject": { "type": "string" } } }, "services.UpdateProjectRequest": { "type": "object", "properties": { "allowed_origins": { "type": "string" }, "content_category": { "type": "string" }, "domains": { "type": "string" }, "logo_url": { "type": "string" }, "max_verification_attempts": { "type": "integer" }, "min_age": { "type": "integer" }, "name": { "type": "string" }, "rate_limit_per_minute": { "type": "integer" } } }, "services.UpdatePromoRequest": { "type": "object", "properties": { "credit_expires_days": { "type": "integer" }, "description": { "type": "string" }, "eligible_plans": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "max_uses": { "type": "integer" }, "valid_until": { "type": "string" } } }, "services.UpdateSurveyRequest": { "type": "object" }, "services.UpdateTenantRequest": { "type": "object", "properties": { "billing_email": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" } } }, "services.VerificationResult": { "type": "object", "properties": { "bracket": { "type": "integer" }, "cascaded": { "type": "array", "items": { "type": "integer" } }, "id_verified": { "type": "boolean" }, "method": { "type": "string" } } }, "telemetry.Event": { "type": "object", "properties": { "hidden": { "description": "Visibility fields (KindVisibility).", "type": "boolean" }, "hidden_ms": { "type": "integer" }, "kind": { "$ref": "#/definitions/telemetry.EventKind" }, "mean": { "description": "Light field (KindLight).", "type": "number" }, "ms": { "type": "integer" }, "reason": { "description": "gyro_unavailable carries a reason string (denied, missing API, …).", "type": "string" }, "stage": { "description": "Latency fields (KindLatency).", "allOf": [ { "$ref": "#/definitions/telemetry.LatencyStage" } ] }, "ts_ms": { "description": "Gyro/Light/Visibility events use TsMs (relative to session start).\nLatency events use Stage + Ms instead.", "type": "integer" }, "x": { "description": "Gyro fields (KindGyro).", "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" } } }, "telemetry.EventKind": { "type": "string", "enum": [ "gyro", "light", "latency", "visibility", "gyro_unavailable" ], "x-enum-varnames": [ "KindGyro", "KindLight", "KindLatency", "KindVisibility", "KindGyroUnavailable" ] }, "telemetry.LatencyStage": { "type": "string", "enum": [ "camera_ready", "first_frame", "capture_pressed" ], "x-enum-varnames": [ "StageCameraReady", "StageFirstFrame", "StageCapturePressed" ] }, "telemetry.Payload": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/definitions/telemetry.Event" } }, "session_token": { "type": "string" }, "summary": { "$ref": "#/definitions/telemetry.Summary" } } }, "telemetry.Summary": { "type": "object", "properties": { "gyro_sample_count": { "type": "integer" }, "gyro_variance_x": { "type": "number" }, "gyro_variance_y": { "type": "number" }, "gyro_variance_z": { "type": "number" }, "hidden_total_ms": { "type": "integer" }, "light_mean": { "type": "number" }, "light_sample_count": { "type": "integer" }, "light_variance": { "type": "number" }, "ms_to_camera_ready": { "type": "integer" }, "ms_to_capture": { "type": "integer" }, "ms_to_first_frame": { "type": "integer" }, "tab_switch_count": { "type": "integer" } } }, "verify.ActionResultRequest": { "type": "object", "properties": { "action_name": { "type": "string" }, "detected_at_ms": { "type": "integer" }, "score": { "type": "number" } } }, "verify.AgeEstimationResultDTO": { "type": "object", "properties": { "confidence": { "type": "number" }, "estimated_age": { "type": "integer" } } }, "verify.CaptureKeyResponseDTO": { "type": "object", "properties": { "expires_in": { "description": "ExpiresIn is the remaining lifetime of the key in seconds. Widget can\nuse this to decide when to request a fresh key (most flows complete\nwell within the TTL so re-fetch is rare).", "type": "integer" }, "key": { "description": "Key is the HMAC key encoded as base64url (unpadded). Widget should\nbase64url-decode to raw bytes before passing to WebCrypto importKey.", "type": "string" } } }, "verify.CompleteSessionDTO": { "type": "object", "required": [ "status" ], "properties": { "completion_reason": { "type": "string" }, "status": { "type": "string", "enum": [ "completed", "failed", "canceled" ] } } }, "verify.CreateAPIKeyRequestDTO": { "type": "object", "required": [ "name" ], "properties": { "callback_url": { "type": "string" }, "expires_at": { "type": "string" }, "name": { "type": "string" }, "rule_id": { "type": "integer" } } }, "verify.EnrollRequestDTO": { "type": "object", "required": [ "image", "user_id" ], "properties": { "image": { "description": "Base64 encoded image", "type": "string" }, "user_id": { "type": "string" } } }, "verify.LightMetricsRequest": { "type": "object", "properties": { "chromatic_response_score": { "type": "number" }, "confidence": { "type": "number" }, "skip_reason": { "type": "string" }, "skipped": { "type": "boolean" }, "spatial_variance_score": { "type": "number" }, "temporal_coherence_score": { "type": "number" } } }, "verify.LivenessResultDTO": { "type": "object" }, "verify.PoseSampleRequest": { "type": "object", "properties": { "pitch": { "type": "number" }, "t": { "type": "integer" }, "yaw": { "type": "number" } } }, "verify.PresignFileDTO": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" } } }, "verify.PresignRequestDTO": { "type": "object", "required": [ "document_type", "files" ], "properties": { "capture_proof_token": { "description": "Wave 1.2: optional capture-proof HMAC token emitted by the widget.\nFormat: base64url(json_payload).hex(HMAC-SHA256(session_key, encoded_payload))\nPayload: { \"task_id\": \"\u003cwill-match-presign-task\u003e\", \"capture_mode\": \"camera\", \"ts\": 1739720400 }\nServer verifies in the worker at S3-download time via pkg/captureguard.\nEmpty when the widget hasn't been upgraded — soft mode applies.", "type": "string" }, "document_type": { "type": "string" }, "files": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/verify.PresignFileDTO" } }, "verification_session_id": { "type": "string" } } }, "verify.RetakeResponseDTO": { "type": "object", "properties": { "previous": { "description": "original session's xtk_ token (for UI \"retrying from...\" display)", "type": "string" }, "token": { "description": "new session's xtk_ token", "type": "string" } } }, "verify.SelfDeclarationDTO": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "declared_age": { "type": "integer" } } }, "verify.VerifyFaceRequestDTO": { "type": "object", "required": [ "image", "user_id" ], "properties": { "image": { "description": "Base64 encoded image", "type": "string" }, "user_id": { "type": "string" } } }, "verify.VerifyRequest": { "type": "object", "required": [ "challenge_id", "token" ], "properties": { "action_results": { "description": "Per-action timing + scores (optional during rollout)", "type": "array", "items": { "$ref": "#/definitions/verify.ActionResultRequest" } }, "challenge_id": { "type": "string" }, "duration_ms": { "type": "integer" }, "frames": { "description": "Optional — future server-side ML analysis", "type": "array", "items": { "type": "string" } }, "light_metrics": { "description": "Light liveness scores (optional)", "allOf": [ { "$ref": "#/definitions/verify.LightMetricsRequest" } ] }, "pose_trajectory": { "description": "Server-authoritative ordered-liveness evidence (numbers only)", "type": "array", "items": { "$ref": "#/definitions/verify.PoseSampleRequest" } }, "token": { "type": "string" } } }, "verify.VerifyURLsRequestDTO": { "type": "object", "properties": { "capture_proof_token": { "description": "Wave 1.2: capture-proof HMAC token. Widget sends here in addition to\nthe presign call so the worker can verify without needing a database\nround-trip to persist/retrieve the token.", "type": "string" }, "document_type": { "type": "string" }, "token": { "type": "string" } } }, "verify.accountDTO": { "type": "object", "properties": { "created_at": { "type": "string" }, "display_name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "has_password": { "type": "boolean" }, "id": { "type": "integer" } } }, "verify.accountLoginRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string" }, "min_age": { "type": "integer" }, "password": { "type": "string" } } }, "verify.accountLoginResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "account": { "$ref": "#/definitions/verify.accountDTO" }, "age_check": { "$ref": "#/definitions/verify.ageCheckDTO" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" } } }, "verify.accountPasskeyDTO": { "type": "object", "properties": { "backup_eligible": { "type": "boolean" }, "backup_state": { "type": "boolean" }, "browser": { "type": "string" }, "created_at": { "type": "string" }, "device_info": { "type": "string" }, "id": { "type": "integer" }, "last_used_at": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" }, "sign_count": { "type": "integer" } } }, "verify.accountRegisterRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "token": { "type": "string" } } }, "verify.ageCheckDTO": { "type": "object", "properties": { "bracket": { "type": "integer" }, "method": { "type": "string" }, "verified": { "type": "boolean" }, "verified_at": { "type": "string" } } }, "verify.captureResponse": { "type": "object", "properties": { "events_accepted": { "type": "integer" }, "stream_entry_id": { "type": "string" } } }, "verify.connectionDTO": { "type": "object", "properties": { "first_connected_at": { "type": "string" }, "last_used_at": { "type": "string" }, "tenant_id": { "type": "integer" }, "use_count": { "type": "integer" } } }, "verify.createChallengeRequest": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string" } } }, "verify.createInitRequest": { "type": "object", "properties": { "callback_url": { "type": "string" }, "failed_url": { "type": "string" }, "liveness_difficulty": { "type": "string" }, "locale": { "type": "string" }, "metadata": { "type": "string" }, "min_age": { "type": "integer" }, "purpose": { "description": "\"age_verification\" (default) or \"id_verification\"", "type": "string" }, "success_url": { "type": "string" }, "theme": { "type": "string" }, "user_id": { "type": "string" } } }, "verify.createInitResponse": { "type": "object", "properties": { "token": { "type": "string" }, "verify_url": { "type": "string" } } }, "verify.issueTokenRequest": { "type": "object", "required": [ "age_bracket" ], "properties": { "age_bracket": { "type": "integer" }, "method": { "type": "string" } } }, "verify.issueTokenResponse": { "type": "object", "properties": { "age_bracket": { "type": "integer" }, "expires_at": { "type": "string" }, "token": { "type": "string" } } }, "verify.quickRegisterRequest": { "type": "object", "properties": { "email": { "type": "string" }, "session_id": { "type": "string" } } }, "verify.reviewRequest": { "type": "object", "properties": { "account_id": { "type": "integer" }, "document_back_key": { "type": "string" }, "document_front_key": { "type": "string" }, "min_age": { "type": "integer" }, "selfie_key": { "type": "string" }, "session_id": { "type": "integer" } } }, "verify.revokeTokenRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } }, "verify.uploadRequest": { "type": "object", "properties": { "doc_country": { "type": "string" }, "doc_type": { "type": "string" }, "flash_pair": { "$ref": "#/definitions/optical.FlashPairCapture" }, "kind": { "description": "\"flash\" | \"tilt\"", "type": "string" }, "session_token": { "type": "string" }, "tilt_sequence": { "$ref": "#/definitions/optical.TiltSequenceCapture" } } }, "verify.uploadResponse": { "type": "object", "properties": { "confidence": { "type": "number" }, "ovd_detected": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } } }, "verify.verifyTokenRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } }, "verify.verifyTokenResponse": { "type": "object", "properties": { "age_bracket": { "type": "integer" }, "expires_at": { "type": "string" }, "method": { "type": "string" }, "valid": { "type": "boolean" } } }, "verify.widgetFeedbackRequest": { "type": "object", "properties": { "comment": { "type": "string" }, "outcome": { "description": "success, failed, cancelled", "type": "string" }, "rating": { "type": "integer" }, "session_id": { "type": "string" } } } }, "securityDefinitions": { "ApiKeyAuth": { "description": "API key authentication for SDK endpoints (/api/v1/*).", "type": "apiKey", "name": "X-API-Key", "in": "header" }, "BearerAuth": { "description": "JWT Bearer token for dashboard and admin endpoints.", "type": "apiKey", "name": "Authorization", "in": "header" } } }