{ "openapi": "3.0.3", "info": { "title": "quiva.ai Gateway", "description": "API for managing accounts, users, authentication, and payments in the quiva.ai platform", "version": "1.0.0", "contact": { "name": "quiva.ai Support", "url": "https://app.quiva.ai" } }, "servers": [ { "url": "https://api.quiva.ai", "description": "Production API server" } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "SuccessResponse": { "type": "object", "properties": { "message": { "type": "string" } } }, "CreateAccountRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Account name that members of the account will be using when signing in. It is case-insensitive. Heading and trailing spaces are trimmed" }, "root_first_name": { "type": "string", "description": "Root user first name" }, "root_last_name": { "type": "string", "description": "Root user last name" }, "root_email": { "type": "string", "format": "email", "description": "Root user email. A user is not allowed to use the same email as a root email for multiple accounts." }, "password": { "type": "string", "format": "password", "description": "Root user password.\nIt has to be a new password if the user is new to the system.\nIf the user exists, they must provide their current password.\nNew password requirements:\n- Minimum length: 8 characters \n - Must contain at least one uppercase letter \n - Must contain at least one lowercase letter \n - Must contain at least one digit (number) \n - Must contain at least one special character (punctuation or symbol) \n - Maximum length: 99 characters" }, "country": { "type": "string", "description": "Country" }, "company_name": { "type": "string", "description": "Company name" }, "address": { "type": "string", "description": "Company address" }, "website": { "type": "string", "description": "Company website" }, "phone_number": { "type": "string", "description": "Company phone number" } }, "required": [ "name", "root_email", "password" ] }, "ContactRequest": { "type": "object", "properties": { "to_email": { "type": "string", "format": "email", "description": "Recipient email" }, "subject": { "type": "string", "description": "Email subject" }, "location": { "type": "string", "description": "Location in the application" }, "message": { "type": "string", "description": "Message content" }, "phone_number": { "type": "string", "description": "Phone number" }, "preferred_contact_method": { "type": "string", "description": "Preferred contact method", "enum": [ "emai", "phone" ] } }, "required": [ "to_email", "subject", "message" ] }, "RefreshTokenObject": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID" }, "user_id": { "type": "string", "description": "User ID" }, "account": { "type": "string", "description": "Account name" }, "email": { "type": "string", "format": "email", "description": "User email" }, "role": { "type": "string", "description": "Role" }, "expiry": { "type": "integer", "format": "int64", "description": "Token expiration timestamp" }, "token": { "type": "string", "description": "Refresh token" } } }, "CreateUserRequest": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "role": { "type": "string", "enum": [ "admin", "developer", "monitor", "billing" ], "description": "Role" } }, "required": [ "first_name", "last_name", "email", "role" ] }, "AuthWithApiKeyRequest": { "type": "object", "properties": { "api_key": { "type": "string", "description": "Api key" } }, "required": [ "api_key" ] }, "CompleteAuthWithPasskeyRequest": { "type": "object", "properties": { "account": { "type": "string", "description": "Account name" }, "token": { "type": "string", "description": "MFA token" }, "credential": { "type": "string", "description": "WebAuthn credential" }, "email": { "type": "string", "description": "User email" } }, "required": [ "credential" ] }, "WebAuthCredentialAlias": { "type": "object", "properties": { "id": { "type": "string", "description": "Credential ID (base64 encoded)" }, "alias": { "type": "string", "description": "User-friendly name" }, "created_on": { "type": "string", "description": "Creation date" } }, "required": [ "id", "alias", "created_on" ] }, "ErrorResponse": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Error message" } } }, "StripePrice": { "type": "object", "required": [ "id", "currency", "unit_amount", "amount" ], "properties": { "id": { "type": "string", "description": "Price ID" }, "currency": { "type": "string", "description": "Currency" }, "lookup_key": { "type": "string", "description": "Lookup key" }, "nickname": { "type": "string", "description": "Nickname" }, "unit_amount": { "type": "number", "description": "Unit amount in cents" }, "amount": { "type": "number", "description": "Amount in currency units" }, "metadata": { "type": "object", "description": "Metadata" } } }, "StripeProduct": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Product ID" }, "name": { "type": "string", "description": "Product name" }, "marketing_features": { "type": "array", "description": "Marketing features" }, "description": { "type": "string", "description": "Product description" }, "price": { "$ref": "#/components/schemas/StripePrice", "description": "Default price" }, "metadata": { "type": "object", "description": "Metadata" } } }, "SubItem": { "type": "object", "required": [ "quantity" ], "properties": { "id": { "type": "string", "description": "Subscription item ID" }, "quantity": { "type": "number", "description": "Quantity" }, "price": { "type": "string", "description": "Price ID" } } }, "SubscriptionItem": { "type": "object", "required": [ "id", "quantity", "price" ], "properties": { "id": { "type": "string", "description": "Subscription item ID" }, "quantity": { "type": "number", "description": "Quantity" }, "price": { "$ref": "#/components/schemas/StripePrice", "description": "Price" } } }, "SessionObject": { "type": "object", "required": [ "account_id", "user_id", "account", "role", "expiry", "ip", "agent", "platform", "token", "refresh_token", "is_suspended", "location" ], "properties": { "account_id": { "type": "string", "description": "Account ID" }, "user_id": { "type": "string", "description": "User ID" }, "account": { "type": "string", "description": "Account name" }, "email": { "type": "string", "description": "User email" }, "role": { "type": "string", "description": "User role" }, "expiry": { "type": "number", "description": "Subscription" }, "ip": { "type": "string", "description": "IP address" }, "agent": { "type": "string", "description": "User agent" }, "platform": { "type": "string", "description": "Platform" }, "token": { "type": "string", "description": "Authentication token" }, "refresh_token": { "type": "string", "description": "Refresh token" }, "is_suspended": { "type": "boolean", "description": "Whether the user is suspended" }, "location": { "type": "string", "description": "Location" } } }, "UpdateUserRequest": { "type": "object", "properties": { "email": { "type": "string", "description": "User email (optional, defaults to current user)" }, "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "sound": { "type": "boolean", "description": "Enable sound" }, "theme": { "type": "string", "description": "UI theme (light, dark, auto)" }, "totp_enabled": { "type": "boolean", "description": "Enable TOTP authentication" }, "passkey_enabled": { "type": "boolean", "description": "Enable passkey authentication" } } }, "MfaInfo": { "type": "object", "required": [ "passkey_enabled", "totp_enabled" ], "properties": { "passkey_enabled": { "type": "boolean", "description": "Whether passkey authentication is enabled" }, "totp_enabled": { "type": "boolean", "description": "Whether TOTP authentication is enabled" } } }, "UserInfo": { "type": "object", "required": [ "email", "role", "is_suspended", "email_confirmed", "first_name", "last_name", "invitation_pending" ], "properties": { "email": { "type": "string", "description": "User email" }, "role": { "type": "string", "description": "Role" }, "is_suspended": { "type": "boolean", "description": "Whether the user is suspended" }, "email_confirmed": { "type": "boolean", "description": "Whether the email is confirmed" }, "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "invitation_pending": { "type": "boolean", "description": "Whether the invitation is pending" } } }, "CheckoutURLRequest": { "type": "object", "required": [ "base_subscription", "message" ], "properties": { "base_subscription": { "type": "string", "description": "Base subscription price ID" }, "addons": { "type": "array", "description": "Subscription addons", "items": { "type": "object", "required": [ "id", "type", "quantity" ], "properties": { "id": { "type": "string", "description": "Addon price ID" }, "type": { "type": "string", "description": "Addon type" }, "quantity": { "type": "number", "description": "Quantity" } } } } } }, "UserProfileImage": { "type": "object", "properties": { "name": { "type": "string", "description": "File name" }, "contentType": { "type": "string", "description": "Content type" } } }, "AccountPublicInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Account name (normalized)" }, "id": { "type": "string", "description": "Account unique identifier - 10 digits" }, "display_name": { "type": "string", "description": "Account display name" }, "root_email": { "type": "string", "format": "email", "description": "Root user email address" }, "subscription_status": { "type": "string", "description": "Subscription status", "enum": [ "active", "pending", "cancelled" ] }, "subscription_plan": { "type": "string", "description": "Subscription plan" }, "emergency_credit": { "type": "number", "format": "float", "description": "Emergency credit amount" }, "country": { "type": "string", "description": "Country" }, "company_name": { "type": "string", "description": "Company name" }, "address": { "type": "string", "description": "Address" }, "website": { "type": "string", "description": "Website" }, "phone_number": { "type": "string", "description": "Phone number" }, "scheduled_for_deletion": { "type": "boolean", "description": "Whether the account is scheduled for deletion" }, "deletion_date": { "type": "string", "format": "date-time", "description": "If the account is scheduled for deletion, it will be deleted on this date" }, "region": { "type": "string", "description": "Region" }, "provider": { "type": "string", "description": "Provider" }, "bstier": { "type": "integer", "description": "BS tier" }, "cloud": { "type": "boolean", "description": "Cloud functionality enabled. It true, the user has access to quiva.ai Cloud" }, "hub": { "type": "boolean", "description": "Hub functionality enabled. It true, the user has access to quiva.ai Hub" } } }, "UpdateAccountRequest": { "type": "object", "properties": { "country": { "type": "string", "description": "Country" }, "company_name": { "type": "string", "description": "Company name" }, "address": { "type": "string", "description": "Address" }, "website": { "type": "string", "description": "Website" }, "phone_number": { "type": "string", "description": "Phone number" }, "onboarding_progress": { "type": "object", "description": "Onboarding progress" }, "region": { "type": "string", "description": "Region" }, "provider": { "type": "string", "description": "Provider" }, "cloud": { "type": "boolean", "description": "Cloud enabled" }, "hub": { "type": "boolean", "description": "Hub enabled" } } }, "RefreshTokenRequest": { "type": "object", "properties": { "auth_token": { "type": "string", "description": "Current authentication token" }, "refresh_token": { "type": "string", "description": "Refresh token to use for generating a new authentication token" } }, "required": [ "auth_token", "refresh_token" ], "example": { "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }, "ExportRequest": { "type": "object", "properties": { "export": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the export within the account" }, "subject": { "type": "string", "description": "Subject pattern defining what is being exported" }, "token_position": { "type": "integer", "description": "Optional parameter that determines how authentication is handled" }, "type": { "type": "string", "enum": [ "stream", "service" ], "description": "Type of resource being exported" } }, "required": [ "name", "subject", "type" ] } }, "required": [ "export" ] }, "ImportRequest": { "type": "object", "properties": { "import": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the import within the account" }, "subject": { "type": "string", "description": "Subject pattern to be imported" }, "account": { "type": "string", "description": "Account from which the resource is being imported" }, "token_position": { "type": "integer", "description": "Optional parameter for authentication handling" } }, "required": [ "name", "subject", "account" ] } }, "required": [ "import" ] }, "CredentialAssertion": { "type": "object", "description": "WebAuthn credential assertion options for the client to process", "properties": { "challenge": { "type": "string", "description": "Base64-encoded challenge to be signed by the authenticator" }, "timeout": { "type": "integer", "description": "Time in milliseconds the user has to respond to the authentication prompt" }, "rpId": { "type": "string", "description": "Relying party identifier (usually the domain name)" }, "allowCredentials": { "type": "array", "description": "List of credentials that are allowed for this authentication", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Base64-encoded credential ID" }, "type": { "type": "string", "description": "Credential type (e.g., 'public-key')" }, "transports": { "type": "array", "description": "List of allowed transports (e.g., 'internal', 'usb')", "items": { "type": "string" } } } } }, "userVerification": { "type": "string", "description": "User verification requirement (e.g., 'preferred', 'required')" } } }, "BeginAuthWithPasskeyRequest": { "type": "object", "properties": { "account": { "type": "string", "description": "Account name (optional)" }, "email": { "type": "string", "format": "email", "description": "User's email address" } }, "required": [ "email" ], "example": { "email": "user@example.com", "account": "acme" } }, "AuthWithRecoveryCodeRequest": { "type": "object", "properties": { "token": { "type": "string", "description": "MFA token received from password authentication" }, "code": { "type": "string", "description": "Recovery code" } }, "required": [ "token", "code" ], "example": { "token": "mfa_token_abcdef1234567890", "code": "ABCD-1234" } }, "AuthWithTOTPRequest": { "type": "object", "properties": { "token": { "type": "string", "description": "MFA token received from password authentication" }, "code": { "type": "string", "description": "6-digit TOTP code from authenticator app" }, "email": { "type": "string", "format": "email", "description": "User's email address (optional when authenticated)" } }, "required": [ "token", "code" ], "example": { "token": "mfa_token_abcdef1234567890", "code": "123456" } }, "ApiKeyRequest": { "type": "object", "properties": { "key_name": { "type": "string", "description": "API key name" } }, "required": [ "key_name" ] }, "ApiKeyResponse": { "type": "object", "properties": { "key": { "type": "string", "description": "API key" }, "name": { "type": "string", "description": "API key name" }, "created_on": { "type": "string", "format": "date-time", "description": "Creation date" }, "expires_on": { "type": "string", "format": "date-time", "description": "Expiration date" }, "creds": { "type": "string", "description": "API credentials" } } }, "DeleteApiKeyRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email (optional, defaults to current user)" }, "key": { "type": "string", "description": "API key" }, "id": { "type": "string", "description": "API key ID (alternative to key)" } } }, "ViewApiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "API key ID" }, "name": { "type": "string", "description": "API key name" }, "last_4_characters": { "type": "string", "description": "Last 4 characters of API key" }, "created_on": { "type": "string", "format": "date-time", "description": "Creation date" }, "expires_on": { "type": "string", "format": "date-time", "description": "Expiration date" }, "account": { "type": "string", "description": "Account name" } } }, "AuthWithPasswordRequest": { "type": "object", "properties": { "account": { "type": "string", "description": "Account name (optional). If not provided and the user is a root user, their root account will be used." }, "email": { "type": "string", "format": "email", "description": "User's email address" }, "password": { "type": "string", "format": "password", "description": "User's password" } }, "required": [ "email", "password" ], "example": { "account": "acme", "email": "user@example.com", "password": "SecurePassword123" } }, "AuthResponse": { "type": "object", "properties": { "refresh_token": { "type": "string", "description": "Refresh token" }, "auth_token": { "type": "string", "description": "Authentication token" }, "passkey_enabled": { "type": "boolean", "description": "Whether passkey authentication is enabled" }, "totp_enabled": { "type": "boolean", "description": "Whether TOTP authentication is enabled" } } }, "MfaRequiredResponse": { "type": "object", "properties": { "token": { "type": "string", "description": "MFA token" }, "passkey_enabled": { "type": "boolean", "description": "Whether passkey authentication is enabled" }, "totp_enabled": { "type": "boolean", "description": "Whether TOTP authentication is enabled" } } }, "ProfileImageUploadRequest": { "type": "object", "properties": { "file_name": { "type": "string", "description": "File name" }, "file": { "type": "string", "format": "byte", "description": "Base64 encoded file content" }, "content_type": { "type": "string", "description": "Content type" }, "is_chunk": { "type": "boolean", "description": "Whether the file is being uploaded in chunks" }, "chunk_index": { "type": "integer", "description": "Current chunk index" }, "total_chunks": { "type": "integer", "description": "Total number of chunks" } }, "required": [ "file_name", "file", "content_type" ] } } }, "tags": [ { "name": "Account Management", "description": "Operations related to account creation, updating, and deletion" }, { "name": "User Management", "description": "Operations related to user creation, updating, and deletion" }, { "name": "Authentication", "description": "Operations related to authentication and session management" }, { "name": "API Keys", "description": "Operations related to API key management" }, { "name": "Multi-Factor Authentication", "description": "Operations related to MFA setup and verification" }, { "name": "Payment", "description": "Operations related to subscription and payment management" }, { "name": "Mesh Nodes", "description": "Operations related to mesh node management" } ], "paths": { "/accounts/oauth/login": { "get": { "summary": "Initiate OAuth login flow", "description": "Generates OAuth URL for authentication with external providers (Auth0)", "tags": [ "Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.oauth-login", "security": [], "operationId": "getOAuthLoginUrl", "parameters": [ { "name": "Referer", "in": "header", "required": true, "description": "Referer URL", "schema": { "type": "string" }, "example": "https://app.staging.quiva.ai/" }, { "name": "account", "in": "query", "required": true, "description": "Account identifier for the login request", "schema": { "type": "string" } }, { "name": "connection", "in": "query", "required": false, "description": "OAuth connection type (e.g., github, google-oauth2)", "schema": { "type": "string" }, "examples": { "github": { "value": "github", "description": "GitHub OAuth connection" }, "google": { "value": "google-oauth2", "description": "Google OAuth connection" } } } ], "responses": { "200": { "description": "OAuth URL generated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "oauth_url": { "type": "string", "format": "uri", "description": "URL to redirect user for OAuth authentication", "example": "https://domain.auth0.com/authorize?client_id=...&response_type=code&redirect_uri=...&state=..." } } } } } } } }, "400": { "description": "Bad request - missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/accounts/oauth/callback": { "get": { "summary": "OAuth callback handler", "description": "Handles OAuth callback from external authentication provider", "tags": [ "Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.oauth-callback", "security": [], "operationId": "handleOAuthCallback", "parameters": [ { "name": "code", "in": "query", "required": true, "description": "Authorization code from OAuth provider", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "description": "State parameter to prevent CSRF attacks", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authentication successful - typically redirects user", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Success response (implementation may vary based on authOrMFA function)" } } } } } }, "400": { "description": "Bad request - invalid parameters or authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/accounts/info": { "get": { "summary": "Get account information", "description": "Retrieves comprehensive information about the authenticated user's current account in a public-facing format (no sensitive data is returned).", "operationId": "getAccountInfo", "x-resource-type": "service", "x-resource": "microstrate.accounts.get.info", "tags": [ "Account Management" ], "responses": { "200": { "description": "Account information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountPublicInfo" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/api-key": { "post": { "summary": "Issue API key", "description": "Issues a new API key for the specified user\n- This function nables users to generate programmatic access credentials for quiva.ai API as well as credentials for CLI access. This feature allows developers to integrate the platform's capabilities into external applications, automation scripts, or CI/CD pipelines without requiring interactive login sessions.", "operationId": "issueApiKey", "x-resource-type": "service", "x-resource": "microstrate.accounts.post.api-key", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyRequest" } } } }, "responses": { "200": { "description": "API key created successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKeyResponse" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete API key", "description": "Delete an API key.\n- A key can be delted by providing the full key or by id.\n- Deleted API keys cannot be recovered", "operationId": "deleteApiKey", "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.api-key", "tags": [ "API Keys" ], "parameters": [ { "name": "key", "in": "query", "description": "Full API key (available for preview only on creation)", "required": false, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Key id (available in the key list)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key deleted successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKeyResponse" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/api-keys": { "get": { "summary": "View API keys", "description": "Retrieves the metadate for all API keys for the specified user.\n- The function allows users to view the metadata for all active API keys for their own account\n- Root and administrator users can view API keys metadata associated with other users on the same account.", "operationId": "viewApiKeys", "x-resource-type": "service", "x-resource": "microstrate.accounts.get.api-keys", "tags": [ "API Keys" ], "parameters": [ { "name": "email", "in": "query", "description": "User email (optional, defaults to current user)", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "API keys retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ViewApiKey" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-with-password": { "post": { "tags": [ "Authentication" ], "summary": "Authenticate with password", "description": "Authenticates a user with their email and password. If MFA is enabled, returns an MFA token that must be used with a subsequent authentication request.", "operationId": "authWithPassword", "x-resource": "microstrate.accounts.post.auth-with-password", "x-resource-type": "service", "security": [], "requestBody": { "description": "Authentication credentials", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithPasswordRequest" }, "examples": { "basicAuth": { "summary": "Basic authentication", "value": { "email": "user@example.com", "password": "SecurePassword123" } }, "withAccount": { "summary": "With account specified", "value": { "account": "acme", "email": "user@example.com", "password": "SecurePassword123" } } } } } }, "responses": { "200": { "description": "Authentication successful or MFA required", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/AuthResponse" }, { "$ref": "#/components/schemas/MfaRequiredResponse" } ] } } }, "examples": { "authSuccess": { "summary": "Authentication successful (no MFA)", "value": { "data": { "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "passkey_enabled": false, "totp_enabled": false, "account": { "name": "acme", "id": "acct_12345", "display_name": "ACME Corporation", "root_email": "admin@acme.com", "subscription_status": "active" } } } }, "mfaRequired": { "summary": "MFA verification required", "value": { "data": { "token": "mfa_token_abcdef1234567890", "passkey_enabled": true, "totp_enabled": true } } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid credentials" } } } } } } }, "/accounts/profile-image": { "post": { "summary": "Upload profile image", "description": "Uploads a profile image for the user", "operationId": "uploadProfileImage", "x-resource-type": "service", "x-resource": "microstrate.accounts.post.profile-image", "tags": [ "User Management" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileImageUploadRequest" } } } }, "responses": { "200": { "description": "Profile image uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete profile image", "description": "Deletes the user's profile image", "operationId": "deleteProfileImage", "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.profile-image", "tags": [ "User Management" ], "responses": { "200": { "description": "Profile image deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/recovery-codes": { "post": { "summary": "Issue recovery codes", "description": "Generates new recovery codes for a user", "operationId": "issueRecoveryCodes", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.recovery-codes", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email (optional, defaults to current user)" } } }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "Recovery codes issued successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string" } } } }, "example": { "data": [ "ABCD-1234", "EFGH-5678", "IJKL-9012" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "View recovery codes", "description": "Retrieves existing recovery codes for a user", "operationId": "viewRecoveryCodes", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.recovery-codes", "parameters": [ { "name": "email", "in": "query", "description": "User email (optional, defaults to current user)", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "Recovery codes retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string" } } } }, "example": { "data": [ "ABCD-1234", "EFGH-5678", "IJKL-9012" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-with-recovery-code": { "post": { "tags": [ "Authentication", "Multi-Factor Authentication" ], "summary": "Authenticate with recovery code", "description": "Complete authentication using a recovery code after initial password verification. Recovery codes are one-time use.", "operationId": "authWithRecoveryCode", "x-resource": "microstrate.accounts.post.auth-with-recovery-code", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithRecoveryCodeRequest" }, "example": { "token": "mfa_token_abcdef1234567890", "code": "ABCD-1234" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthResponse" } } } } } }, "401": { "description": "Invalid recovery code or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Used or invalid recovery code" } } } } } } }, "/accounts/remove-user": { "delete": { "summary": "Remove user from account", "description": "Removes a user from the current account", "operationId": "removeUser", "tags": [ "User Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" } }, "required": [ "email" ] }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "User removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/request-reset-password": { "post": { "summary": "Request password reset", "description": "Requests a password reset for a user", "operationId": "requestResetPassword", "tags": [ "Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.request-reset-password", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" } }, "required": [ "email" ] }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "Password reset request processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/accounts/reset-password": { "post": { "summary": "Reset password", "description": "Resets a user's password", "operationId": "resetPassword", "tags": [ "Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.reset-password", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" }, "token": { "type": "string", "description": "Password reset token" }, "password": { "type": "string", "description": "Current password (required when authenticated)" }, "new_password": { "type": "string", "description": "New password.\n\nRequirements:\n- Minimum length: 8 characters \n - Must contain at least one uppercase letter \n - Must contain at least one lowercase letter \n - Must contain at least one digit (number) \n - Must contain at least one special character (punctuation or symbol) \n - Maximum length: 99 characters" } }, "required": [ "token", "new_password" ] }, "example": { "email": "user@example.com", "token": "abcdef123456", "new_password": "NewSecureP@ssw0rd!" } } } }, "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/set-password": { "post": { "summary": "Set password", "description": "Sets a password for a new user", "operationId": "setPassword", "tags": [ "Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.set-password", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Set password token" }, "password": { "type": "string", "description": "New password.\n\nRequirements:\n- Minimum length: 8 characters \n - Must contain at least one uppercase letter \n - Must contain at least one lowercase letter \n - Must contain at least one digit (number) \n - Must contain at least one special character (punctuation or symbol) \n - Maximum length: 99 characters" } }, "required": [ "token", "password" ] }, "example": { "token": "abcdef123456", "password": "SecureP@ssw0rd!" } } } }, "responses": { "200": { "description": "Password set successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "account_id": { "type": "string" }, "user_id": { "type": "string" }, "account": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/generate-totp-key": { "post": { "summary": "Generate TOTP key", "description": "Generates a TOTP key for multi-factor authentication", "operationId": "generateTotpKey", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.generate-totp-key", "responses": { "200": { "description": "TOTP key generated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "otpauth_url": { "type": "string", "description": "OTP Auth URL for QR code generation" }, "secret": { "type": "string", "description": "TOTP secret key" } } } } }, "example": { "data": { "otpauth_url": "otpauth://totp/quiva.ai:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=quiva.ai", "secret": "JBSWY3DPEHPK3PXP" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/confirm-totp-registration": { "post": { "summary": "Confirm TOTP registration", "description": "Confirms a TOTP registration by validating a code", "operationId": "confirmTotpRegistration", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.confirm-totp-registration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "TOTP code" }, "secret": { "type": "string", "description": "TOTP secret key" } }, "required": [ "code", "secret" ] }, "example": { "code": "123456", "secret": "JBSWY3DPEHPK3PXP" } } } }, "responses": { "200": { "description": "TOTP registration confirmed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "recovery_codes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-with-totp": { "post": { "tags": [ "Authentication", "Multi-Factor Authentication" ], "summary": "Authenticate with TOTP", "description": "Complete authentication using a Time-based One-Time Password (TOTP) after initial password verification.", "operationId": "authWithTotp", "x-resource": "microstrate.accounts.post.auth-with-totp", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithTOTPRequest" }, "example": { "token": "mfa_token_abcdef1234567890", "code": "123456" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthResponse" } } } } } }, "401": { "description": "Invalid TOTP code or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } } } } }, "/accounts/totp": { "delete": { "summary": "Remove TOTP", "description": "Disables TOTP authentication for a user", "operationId": "removeTotp", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.totp", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email (optional, defaults to current user)" } } }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "TOTP removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/set-emergency-credit": { "patch": { "summary": "Set emergency credit", "description": "Sets the emergency credit amount for an account.\n- Allows users with appropriate permissions (root, admin, or billing roles) to configure a maximum monthly emergency budget.\n- For accounts with fixed resource allocations, emergency credit funds the provisioning of additional resources when regular allocations are exhausted.", "operationId": "setEmergencyCredit", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.patch.set-emergency-credit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emergency_credit": { "type": "number", "format": "float", "description": "Emergency credit amount" } }, "required": [ "emergency_credit" ] }, "example": { "emergency_credit": 100 } } } }, "responses": { "200": { "description": "Emergency credit set successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/rename": { "patch": { "summary": "Rename account", "description": "Renames an account\n- Allows the root user of an account to change the display name and internal name of their account\n- They must request a verification code to be able to finalize the process (see **/accounts/email-code**)\n- Once an account name is changed, all user sessions will be automatically revoked. Affected users will be notified about the change by email.", "operationId": "renameAccount", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.patch.rename-account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_name": { "type": "string", "description": "New account name. Cannot clash with the name of another account on the platform" }, "email_code": { "type": "string", "description": "Email verification code. To obtain one, see **/accounts/email-code**" } }, "required": [ "new_name", "email_code" ] }, "example": { "new_name": "new-acme", "email_code": "123456" } } } }, "responses": { "200": { "description": "Account renamed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Account name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts": { "post": { "summary": "Create account", "description": "- Creates a new account and a user if the provided email does not exist on the system.\n- Associates the user with the account with root privileges.\n- Sends an email to the user to verify their email address if the email is not already verified on the system.\n- A user can be a member of any number of accounts but they can be a root of at most one account.", "operationId": "createAccount", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.create-account", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountRequest" }, "example": { "name": "acme", "root_first_name": "John", "root_last_name": "Doe", "root_email": "admin@acme.com", "password": "SecureP@ssw0rd!", "country": "US", "company_name": "ACME Corporation", "address": "123 Main St, Anytown, USA", "website": "https://acme.com", "phone_number": "+1234567890" } } } }, "responses": { "200": { "description": "Account created successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "email_confirmed": { "type": "boolean" } } } } }, "example": { "data": { "email_confirmed": false, "description": "This flag confirms whether a new or an existing user is the root of the newly created account." } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update account", "description": "Updates account information.\n - An update can be made to any of the non-critical editable account properties only by root and admin users.\n - Critical account properties such as name, ID, and root email address cannot be changed with this request\n - To update *name*, see **/accounts/rename**\n- To update *root_email*, see **/accounts/request-email-address-change**", "operationId": "updateAccount", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.patch.update-account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountRequest" }, "example": { "country": "US", "company_name": "ACME Corporation Updated", "address": "456 New St, Anytown, USA", "website": "https://new-acme.com", "phone_number": "+9876543210", "region": "us-east-1", "provider": "aws", "cloud": true, "hub": false } } } }, "responses": { "200": { "description": "Account updated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountPublicInfo" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/users": { "post": { "summary": "Create/Add user", "description": "Creates a new user and sends an invitation email if the user does not exist. Adds the new or existing user to the current account. If the user already exists and is already a member of the account, an error is returned \n - If the user already exists but isn't a member of the account, they are added without creating a new user record \n - The user won't be able to access the account until they complete the activation process by setting their password \n - For security, new users must set their own password via the activation link \n - The function schedules cleanup tasks to remove unactivated user accounts after a certain period of time (48 hours)", "operationId": "createUser", "tags": [ "User Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.create-user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" }, "example": { "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com", "role": "developer" } } } }, "responses": { "200": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/account": { "delete": { "summary": "Delete account", "description": "Deletes the current account.\n- Allows the root user of an account to delete the entire account from the platform.\n- The root user must request a verification code to be able to finalize the process (see **/accounts/email-code**)\n- This is a significant operation that removes all account data and revokes access for all users associated with the account.\n- Users, however, are not deleted and they can continue to sign in to the platform if they are members of any other active accounts.\n - There is an option to delete the account immediately or in 14 days. If the latter, the deletion can be unscheduled (see **/accounts/cancel-account-deletion**)", "operationId": "deleteAccount", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "in_14_days": { "type": "boolean", "description": "Schedule deletion in 14 days. If this flag is set to true, the account data will not be deactivated immediately and will be accessible in the next 14 days. After this period is up, it will no longer be possible to log in with the account. If the root user wishes to recover it, they can contact a platform administrator up to a year after the account was deleted." }, "email_code": { "type": "string", "description": "Email verification code. To obtain one, see **/accounts/email-code**" } }, "required": [ "email_code" ] }, "example": { "in_14_days": true, "email_code": "123456" } } } }, "responses": { "200": { "description": "Account scheduled for deletion or deleted successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" }, "deletion_date": { "type": "string", "format": "date-time" } } } } }, "example": { "data": { "message": "The accounts is going to be deleted on 2023-05-12T12:34:56Z", "deletion_date": "2023-05-12T12:34:56Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/cancel-account-deletion": { "post": { "summary": "Cancel account deletion", "description": "Cancels the deletion of an account.\n- Allows the root user of an account to reverse a scheduled account deletion if the current date is before *deletion_date*.", "operationId": "cancelAccountDeletion", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.cancel-account-deletion", "responses": { "200": { "description": "Account deletion cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Account not scheduled for deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/user": { "delete": { "summary": "Delete user", "description": "Deletes the current user", "operationId": "deleteUser", "tags": [ "User Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.user", "parameters": [ { "name": "email_code", "in": "query", "description": "Email verification code. To obtain one, see **/accounts/email-code**", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Cannot delete root user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update user", "description": "Updates user information", "operationId": "updateUser", "tags": [ "User Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.patch.update-user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" }, "example": { "first_name": "John", "last_name": "Smith", "theme": "dark", "sound": true } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/request-email-address-change": { "post": { "summary": "Request email address change", "description": "Initiates an email address change process", "operationId": "requestEmailAddressChange", "tags": [ "User Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.request-email-address-change", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "Current password" }, "token": { "type": "string", "description": "MFA token (required if MFA is enabled)" }, "new_email": { "type": "string", "format": "email", "description": "New email address" } }, "required": [ "new_email" ] }, "example": { "password": "SecureP@ssw0rd!", "new_email": "new.email@example.com" } } } }, "responses": { "200": { "description": "Email change request initiated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/change-email-address-action": { "post": { "summary": "Complete email address change", "description": "Completes an email address change process", "operationId": "changeEmailAddressAction", "tags": [ "User Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.change-email-address-action", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Email change token" } }, "required": [ "token" ] }, "example": { "token": "abcdef123456" } } } }, "responses": { "200": { "description": "Email change action completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/email-code": { "get": { "summary": "Get email verification code", "description": "Sends a verification code to the user's email", "operationId": "getEmailCode", "tags": [ "Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.email-code", "responses": { "200": { "description": "Email code sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/import": { "post": { "summary": "Add import", "description": "Adds a new import to the account.\n- When an account adds an import, it's essentially creating a mapping that allows it to access and utilize resources (such as data streams or services) that are exported by another account. This request creates a trust relationship between accounts where one account can consume resources produced by another.", "operationId": "addImport", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.import", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRequest" } } } }, "responses": { "200": { "description": "Import added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove import", "description": "Removes an import from the account. Allows an account to discontinue the integration with resources from another account. This operation effectively severs the connection to external resources that an account was consuming.", "operationId": "removeImport", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.import", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Import name" } }, "required": [ "name" ] }, "example": { "name": "example-import" } } } }, "responses": { "200": { "description": "Import removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/export": { "post": { "summary": "Add export", "description": "Adds a new export to the account.\n - Enables an account to make its internal resources (such as data streams or services) available to other accounts.", "operationId": "addExport", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.export", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } }, "responses": { "200": { "description": "Export added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove export", "description": "Removes an export from the account.\n - Allows an account to discontinue sharing a previously exported resource with other accounts. This operation effectively revokes external access to the specified resource.", "operationId": "removeExport", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.export", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Export name" } }, "required": [ "name" ] }, "example": { "name": "example-export" } } } }, "responses": { "200": { "description": "Export removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/users/list": { "get": { "summary": "List users by account", "description": "Lists all users in the current account", "operationId": "listUsersByAccount", "tags": [ "User Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.list-users-by-account", "responses": { "200": { "description": "Users retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserInfo" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/list": { "get": { "summary": "List accounts by user", "description": "Lists all accounts for the current user", "operationId": "listAccountsByUser", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.list-accounts-by-user", "responses": { "200": { "description": "Accounts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string" } } } }, "example": { "data": [ "acct_123456789", "acct_987654321" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/mesh-nodes": { "put": { "summary": "Update mesh nodes", "description": "Updates the number of mesh nodes and the available regions", "operationId": "updateMeshNodes", "tags": [ "Mesh Nodes" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.put.update-mesh-nodes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "num_nodes": { "type": "number", "description": "has to be an odd number - 1, 2 or 5" }, "regions": { "type": "array", "items": { "type": "string", "description": "Availability regions. The number of specified regions cannot exceed the number of regions" } } }, "required": [ "num_nodes", "regions" ] }, "example": { "num_nodes": 3, "regions": [ "eu" ] } } } }, "responses": { "200": { "description": "Mesh nodes updated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/begin-passkey-registration": { "post": { "summary": "Begin passkey registration", "description": "Initiates the passkey registration process", "operationId": "beginPasskeyRegistration", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.begin-passkey-registration", "responses": { "200": { "description": "Passkey registration initiated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "WebAuthn registration options" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/complete-passkey-registration": { "post": { "summary": "Complete passkey registration", "description": "Completes the passkey registration process", "operationId": "completePasskeyRegistration", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.complete-passkey-registration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "description": "WebAuthn credential" }, "credential_alias": { "type": "string", "description": "User-friendly name for the passkey" } }, "required": [ "credential", "credential_alias" ] } } } }, "responses": { "200": { "description": "Passkey registration completed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "passkey": { "$ref": "#/components/schemas/WebAuthCredentialAlias" }, "recovery_codes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/begin-auth-with-passkey": { "post": { "tags": [ "Authentication", "Multi-Factor Authentication" ], "summary": "Begin passkey authentication", "description": "Initiates the WebAuthn passkey authentication flow. Returns a challenge for the client to sign with the user's passkey.", "operationId": "beginAuthWithPasskey", "x-resource": "microstrate.accounts.post.begin-auth-with-passkey", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginAuthWithPasskeyRequest" }, "example": { "email": "user@example.com", "account": "acme" } } } }, "responses": { "200": { "description": "Passkey authentication challenge", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CredentialAssertion" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "User not found or passkeys not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/passkey": { "delete": { "summary": "Remove passkey", "description": "Removes a specific passkey", "operationId": "removePasskey", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.passkey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Passkey ID (base64 encoded)" }, "email": { "type": "string", "format": "email", "description": "User email (optional, defaults to current user)" } }, "required": [ "id" ] }, "example": { "id": "cGFzc2tleV9pZA==", "email": "user@example.com" } } } }, "responses": { "200": { "description": "Passkey removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Passkey not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/role": { "patch": { "summary": "Update user role", "description": "Updates a user's role in an account", "operationId": "updateRole", "tags": [ "User Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.patch.update-role", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" }, "role": { "type": "string", "enum": [ "admin", "developer", "monitor", "billing" ], "description": "New role" } }, "required": [ "email", "role" ] }, "example": { "email": "user@example.com", "role": "admin" } } } }, "responses": { "200": { "description": "Role updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/suspend-user": { "patch": { "summary": "Suspend user", "description": "Suspends or unsuspends a user in an account. Suspended users have no access to any of the resources and services associated with the account", "operationId": "suspendUser", "tags": [ "User Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.patch.suspend-user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" }, "suspend": { "type": "boolean", "description": "Set true to suspend, false to unsuspend" } }, "required": [ "email", "suspend" ] }, "example": { "email": "user@example.com", "suspend": true } } } }, "responses": { "200": { "description": "User suspended/unsuspended successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/user-mfa-info": { "get": { "summary": "Get user MFA info", "description": "Retrieves MFA information for a user", "operationId": "getUserMfaInfo", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.user-mfa-info", "parameters": [ { "name": "email", "in": "query", "description": "User email (optional, defaults to current user)", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "MFA information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MfaInfo" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/user-login-data": { "get": { "summary": "Get user login data", "description": "Retrieves login data for the current user", "operationId": "getUserLoginData", "tags": [ "User Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.user-login-data", "responses": { "200": { "description": "User login data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/AccountPublicInfo" }, "user": { "type": "string", "format": "email" }, "user_id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "role": { "type": "string" }, "mfa": { "$ref": "#/components/schemas/MfaInfo" }, "theme": { "type": "string" }, "sound": { "type": "boolean" }, "profile_image": { "$ref": "#/components/schemas/UserProfileImage" } }, "required": [ "account", "user", "user_id", "role" ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/token-validate": { "post": { "tags": [ "Authentication" ], "summary": "Validate token", "description": "Validates an authentication or refresh token.", "operationId": "validateToken", "x-resource": "microstrate.accounts.post.token-validate", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token to validate" } }, "required": [ "token" ] }, "example": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } }, "responses": { "200": { "description": "Token validation result", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "boolean" } } }, "example": { "data": true } } } } } } }, "/accounts/api-creds": { "get": { "summary": "Get API credentials", "description": "Retrieves credentials for a specific API key. -Allows users to retrieve the full credential string that can be used with the CLI.", "operationId": "getApiCreds", "tags": [ "API Keys" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.api-creds", "parameters": [ { "name": "key", "in": "query", "description": "Full API key", "schema": { "type": "string" }, "required": true, "example": "ms-d28f9a3c5b6e7d4a1c8f9a3c5b6e7d4a" } ], "responses": { "200": { "description": "API credentials retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string" } } }, "example": { "data": "-----BEGIN quiva.ai USER JWT-----\n[JWT TOKEN]\n------END quiva.ai USER JWT------\n************************* IMPORTANT *************************\nBKEY Seed printed below can be used to sign and prove identity.\nBKEYs are sensitive and should be treated as secrets.\n-----BEGIN USER BKEY SEED-----\n[BKEY SEED]\n------END USER BKEY SEED------\n*************************************************************" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-with-api-key": { "post": { "tags": [ "Authentication", "API Keys" ], "summary": "Authenticate with API key", "description": "Authenticates a user using an API key.", "operationId": "authWithApiKey", "x-resource": "microstrate.accounts.post.auth-with-api-key", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithApiKeyRequest" }, "example": { "api_key": "ms-d28f9a3c5b6e7d4a1c8f9a3c5b6e7d4a" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthResponse" } } } } } }, "401": { "description": "Invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } } } } }, "/accounts/mfa-settings": { "patch": { "summary": "Update MFA settings", "description": "Updates multi-factor authentication settings for a user", "operationId": "updateMfaSettings", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.patch.mfa-settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "totp_enabled": { "type": "boolean", "description": "Enable or disable TOTP (Time-based One-Time Password)" }, "passkey_enabled": { "type": "boolean", "description": "Enable or disable passkey authentication" } } }, "example": { "totp_enabled": true, "passkey_enabled": false } } } }, "responses": { "200": { "description": "MFA settings updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/session-tokens": { "get": { "summary": "Get session tokens", "description": "Retrieves all active session tokens for the current user", "operationId": "getSessionTokens", "tags": [ "Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.session-tokens", "responses": { "200": { "description": "Session tokens retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "auth": { "type": "array", "items": { "$ref": "#/components/schemas/SessionObject" } }, "refresh": { "type": "array", "items": { "$ref": "#/components/schemas/RefreshTokenObject" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/auth-token": { "delete": { "summary": "Revoke auth token", "description": "Revokes a specific authentication token", "operationId": "revokeAuthToken", "tags": [ "Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.auth-token", "parameters": [ { "name": "token", "in": "query", "description": "Auth token to revoke", "schema": { "type": "string" }, "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "required": true } ], "responses": { "200": { "description": "Token revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/refresh-token": { "delete": { "summary": "Revoke refresh token", "description": "Revokes a specific refresh token", "operationId": "revokeRefreshToken", "tags": [ "Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.refresh-token", "parameters": [ { "name": "token", "in": "query", "description": "Refresh token to revoke", "schema": { "type": "string" }, "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "required": true } ], "responses": { "200": { "description": "Token revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Authentication" ], "summary": "Refresh authentication token", "description": "Issues a new authentication token using a valid refresh token.", "operationId": "refreshToken", "x-resource": "microstrate.accounts.post.refresh-token", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" }, "example": { "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } }, "responses": { "200": { "description": "New authentication token issued", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthResponse" } } } } } }, "401": { "description": "Invalid or expired tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } } } } }, "/accounts/tokens": { "delete": { "summary": "Revoke all tokens", "description": "Revokes all tokens for a specific user", "operationId": "revokeTokens", "tags": [ "Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.tokens", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email" } }, "required": [ "email" ] }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "Tokens revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/confirm-email": { "post": { "summary": "Confirm email", "description": "Confirms a user's email address using a token or code\n - This process ensures that the person registering or using an email address actually has access to it. When a user registers a new account or adds a new email address to their profile, the system sends a confirmation email containing either a token (a long, randomly generated string) or a numerical code. This function processes the verification when the user clicks the confirmation link in the email or manually enters the provided code. It accepts either:\n- a) A token parameter, which is included in the confirmation link\n- b) A code parameter, which is a shorter numerical sequence that can be manually entered", "operationId": "confirmEmail", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.confirm-email", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Email confirmation token" }, "code": { "type": "string", "description": "Email confirmation code (alternative to token)" } }, "oneOf": [ { "required": [ "token" ] }, { "required": [ "code" ] } ] }, "example": { "token": "abcdef123456" } } } }, "responses": { "200": { "description": "Email confirmed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "account": { "type": "string" }, "email": { "type": "string", "format": "email" }, "account_id": { "type": "string" }, "user_id": { "type": "string" } } } } }, "example": { "data": { "account": "acme", "email": "user@example.com", "account_id": "acct_123456789", "user_id": "usr_123456789" } } } } }, "400": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/resend-confirmation": { "post": { "summary": "Resend email confirmation", "description": "Resends email confirmation link to user. Always returns success for security reasons.", "tags": [ "Account Management" ], "operationId": "resendAccountConfirmation", "security": [], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.resend-confirmation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address to resend confirmation to", "example": "user@example.com" } } } } } }, "responses": { "200": { "description": "Confirmation email sent (always returns success)", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Please check your inbox. If a root account is associated with this email and remains unconfirmed, a reconfirmation message should have been sent." } } } } } } } } } } }, "/accounts/submit-contact-form": { "post": { "summary": "Submit contact form", "description": "Submits a contact form\n- The function provides a structured mechanism for authenticated users to send inquiries, feedback, or support requests directly to the quiva.ai team or specific team members. This communication channel is integrated within the platform, allowing users to reach out for assistance without leaving the application environment.", "operationId": "submitContactForm", "tags": [ "Account Management" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.submit-contact-form", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" }, "example": { "to_email": "support@example.com", "subject": "Billing question", "location": "Account settings", "message": "I have a question about my billing cycle.", "phone_number": "+1234567890", "preferred_contact_method": "email" } } } }, "responses": { "200": { "description": "Contact form submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/complete-auth-with-passkey": { "post": { "tags": [ "Authentication", "Multi-Factor Authentication" ], "summary": "Complete passkey authentication", "description": "Completes the WebAuthn passkey authentication flow by verifying the signed challenge.", "operationId": "completeAuthWithPasskey", "x-resource": "microstrate.accounts.post.complete-auth-with-passkey", "x-resource-type": "service", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteAuthWithPasskeyRequest" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthResponse" } } } } } }, "401": { "description": "Invalid credential or verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/all-passkeys": { "delete": { "summary": "Remove all passkeys", "description": "Removes all passkeys for a user", "operationId": "removeAllPasskeys", "tags": [ "Multi-Factor Authentication" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.all-passkeys", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User email (optional, defaults to current user)" } } }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "All passkeys removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/webhook": { "post": { "summary": "Process payment webhook", "description": "Processes payment webhooks from Stripe", "operationId": "processPaymentWebhook", "tags": [ "Payment" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.payment.webhook", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Stripe webhook event object" } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/products": { "get": { "summary": "Get products", "description": "Retrieves all available products", "operationId": "getProducts", "tags": [ "Payment" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.payment.products", "responses": { "200": { "description": "Products retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StripeProduct" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/prices": { "get": { "summary": "Get prices", "description": "Retrieves all available prices", "operationId": "getPrices", "tags": [ "Payment" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.payment.prices", "responses": { "200": { "description": "Prices retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StripePrice" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/checkout-url": { "post": { "summary": "Get checkout URL", "description": "Generates a Stripe checkout URL for subscription", "operationId": "getCheckoutUrl", "tags": [ "Payment" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.payment.checkout-url", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutURLRequest" }, "example": { "base_subscription": "price_1234567890", "addons": [ { "id": "price_0987654321", "type": "addon", "quantity": 2 } ] } } } }, "responses": { "200": { "description": "Checkout URL generated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string", "format": "uri" } } }, "example": { "data": "https://checkout.stripe.com/c/pay/cs_test_1234567890" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/dashboard-url": { "get": { "summary": "Get dashboard URL", "description": "Generates a Stripe customer portal URL", "operationId": "getDashboardUrl", "tags": [ "Payment" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.payment.dashboard-url", "responses": { "200": { "description": "Dashboard URL generated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string", "format": "uri" } } }, "example": { "data": "https://billing.stripe.com/p/session/live_1234567890" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/subscription-items": { "get": { "summary": "Get subscription items", "description": "Retrieves all items in the current subscription", "operationId": "getSubscriptionItems", "tags": [ "Payment" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.payment.subscription-items", "responses": { "200": { "description": "Subscription items retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "has_default_payment_method": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionItem" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No subscription found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/subscription": { "get": { "summary": "Get subscription", "description": "Retrieves the current subscription", "operationId": "getSubscription", "tags": [ "Payment" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.get.payment.subscription", "responses": { "200": { "description": "Subscription retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Stripe subscription object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No subscription found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update subscription", "description": "Updates the current subscription", "operationId": "updateSubscription", "tags": [ "Payment" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.patch.payment.subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubItem" } } }, "required": [ "items" ] }, "example": { "items": [ { "id": "si_1234567890", "quantity": 2 } ] } } } }, "responses": { "200": { "description": "Subscription updated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Stripe subscription object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No subscription found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Cancel subscription", "description": "Cancels the current subscription", "operationId": "cancelSubscription", "tags": [ "Payment" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.delete.payment.subscription", "responses": { "200": { "description": "Subscription cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Stripe subscription object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No subscription found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/payment/free-subscription": { "post": { "summary": "Create free subscription", "description": "Creates a free subscription", "operationId": "createFreeSubscription", "tags": [ "Payment" ], "x-resource-type": "service", "x-resource": "microstrate.accounts.post.payment.free-subscription", "responses": { "200": { "description": "Free subscription created successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Stripe subscription object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }