{ "openapi": "3.1.0", "info": { "title": "Rakomi API", "version": "1.0.0", "description": "EU-native authentication platform API" }, "servers": [ { "url": "https://api.rakomi.com", "description": "Production" }, { "url": "https://localhost:3001", "description": "Local development" } ], "components": { "schemas": { "OnboardingSignupRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "founder@example.com" }, "password": { "type": "string", "minLength": 12, "maxLength": 128, "example": "SecureP@ssw0rd" }, "tenant_name": { "type": "string", "minLength": 2, "maxLength": 50, "example": "My Project" }, "consent_terms": { "type": "boolean", "enum": [ true ], "description": "Must be true to accept Terms of Service" }, "consent_privacy": { "type": "boolean", "enum": [ true ], "description": "Must be true to acknowledge Privacy Policy" }, "consent_marketing": { "type": "boolean", "default": false, "description": "Optional marketing email consent" }, "idempotency_key": { "type": "string", "minLength": 36, "description": "IETF idempotency key (min 36 chars, UUID4 recommended)" }, "website": { "type": "string", "description": "Leave blank" }, "turnstile_token": { "type": "string", "description": "Cloudflare Turnstile token" } }, "required": [ "email", "password", "tenant_name", "consent_terms", "consent_privacy" ] }, "SdkSupportPolicy": { "type": "object", "properties": { "schemaVersion": { "type": "string", "example": "1" }, "generated_at": { "type": "string", "example": "2026-06-18T00:00:00Z" }, "valid_until": { "type": "string", "example": "2027-06-18" }, "policyUrl": { "type": "string", "example": "https://rakomi.com/.well-known/sdk-support.json" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "package": { "type": "string", "example": "@rakomi/node" }, "registry": { "type": "string", "enum": [ "npm", "spm", "pubdev" ], "example": "npm" }, "major": { "type": "integer", "example": 1 }, "released": { "type": "string", "example": "2026-06-18" }, "supportedUntil": { "type": "string", "example": "2031-06-18" }, "status": { "type": "string", "enum": [ "active", "maintenance", "eol" ], "example": "active" }, "early_eol_reason": { "type": "string" } }, "required": [ "package", "major", "released", "supportedUntil", "status" ] } } }, "required": [ "schemaVersion", "generated_at", "valid_until", "policyUrl", "entries" ] }, "DpiaVcGateLink": { "type": "object", "properties": { "dpia_key": { "type": "string", "format": "uuid", "description": "The cited DPIA chain key (26.3 dpia_key)" }, "dpia_version": { "type": "integer", "minimum": 1, "description": "The DPIA head version captured at link time" }, "dpia_content_hash": { "type": "string", "description": "The cited DPIA head content_hash captured at link time" }, "linked_at": { "type": "string", "description": "RFC 3339 UTC instant the link was recorded" } }, "required": [ "dpia_key", "dpia_version", "dpia_content_hash", "linked_at" ] }, "StepUpPasswordRequest": { "type": "object", "properties": { "password": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "password" ] }, "StepUpMagicLinkInitiateRequest": { "type": "object", "properties": { "action_hint": { "type": "string", "maxLength": 80 } } }, "StepUpMagicLinkVerifyRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "token" ] }, "StepUpEmailOtpInitiateRequest": { "type": "object", "properties": { "action_hint": { "type": "string", "maxLength": 80 } } }, "StepUpEmailOtpVerifyRequest": { "type": "object", "properties": { "otp": { "type": "string", "minLength": 1, "maxLength": 8 } }, "required": [ "otp" ] }, "StepUpPasskeyVerifyRequest": { "type": "object", "properties": { "assertion": { "type": "object", "properties": { "id": { "type": "string" }, "rawId": { "type": "string" }, "type": { "type": "string" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string" }, "authenticatorData": { "type": "string" }, "signature": { "type": "string" }, "userHandle": { "type": "string" } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] }, "clientExtensionResults": { "type": "object", "additionalProperties": {} }, "authenticatorAttachment": { "type": "string" } }, "required": [ "id", "rawId", "type", "response" ] } }, "required": [ "assertion" ] }, "PasskeyRegisterFinishRequest": { "type": "object", "properties": { "response": {}, "nickname": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "PasskeyAssertBeginRequest": { "type": "object", "properties": { "user_handle": { "type": "string" } } }, "PasskeyAssertFinishRequest": { "type": "object", "properties": { "response": {} } }, "PasskeyUpdateRequest": { "type": "object", "properties": { "nickname": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "nickname" ] }, "RegisterRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 12, "maxLength": 128 }, "consent": { "type": "boolean" }, "date_of_birth": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Required when the tenant has minor protection enabled; format YYYY-MM-DD. Used solely for GDPR Art. 8 minor-protection age determination — stored encrypted at rest, never echoed in any token, log, or response." }, "age_verification_token": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "email", "password", "consent" ] }, "AnonymousSigninResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "number" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "is_anonymous": { "type": "boolean", "enum": [ true ] }, "created_at": { "type": "string" } }, "required": [ "id", "is_anonymous", "created_at" ] } }, "required": [ "access_token", "refresh_token", "expires_in", "token_type", "user" ] }, "AnonymousSigninRequest": { "type": "object", "properties": { "public_metadata": { "type": "object", "additionalProperties": {} } } }, "LoginRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 12, "maxLength": 128 } }, "required": [ "email", "password" ] }, "MfaVerifyLoginRequest": { "type": "object", "properties": { "mfa_challenge_token": { "type": "string", "minLength": 1 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "mfa_challenge_token", "code" ] }, "MfaVerifySetupRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^\\d{6}$" } }, "required": [ "code" ] }, "MfaDisableRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "password": { "type": "string", "minLength": 1 } }, "required": [ "code", "password" ] }, "MfaRegenerateCodesRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^\\d{6}$" }, "password": { "type": "string", "minLength": 1 } }, "required": [ "code", "password" ] }, "RefreshTokenRequest": { "type": "object", "properties": { "refresh_token": { "type": "string", "minLength": 1, "description": "The refresh token from login or previous refresh", "example": "019508a0-1234-7890-abcd-ef1234567890:a1b2c3d4e5f6..." } }, "required": [ "refresh_token" ] }, "VerifyEmailRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 } }, "required": [ "token" ] }, "ResendVerificationRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] }, "ForgotPasswordRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] }, "ResetPasswordRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 }, "password": { "type": "string", "minLength": 12, "maxLength": 128 } }, "required": [ "token", "password" ] }, "ChangePasswordRequest": { "type": "object", "properties": { "current_password": { "type": "string", "minLength": 1 }, "new_password": { "type": "string", "minLength": 12, "maxLength": 128 } }, "required": [ "current_password", "new_password" ] }, "UserMagicLinkRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "oauth_params": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "response_type": { "type": "string" }, "code_challenge": { "type": "string" }, "code_challenge_method": { "type": "string" }, "scope": { "type": "string" }, "state": { "type": "string" }, "nonce": { "type": "string" }, "resource": { "type": "string" } }, "required": [ "client_id", "redirect_uri" ] } }, "required": [ "email" ] }, "UserMagicLinkVerifyRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 }, "resume_binding": { "type": "string", "maxLength": 64 } }, "required": [ "token" ] }, "ParentalConsentRequest": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email" }, "password": { "type": "string", "minLength": 1, "maxLength": 1024 }, "guardian_email": { "type": "string", "maxLength": 254, "format": "email" } }, "required": [ "email", "password", "guardian_email" ], "additionalProperties": false }, "GuardianConsentConsume": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 512 }, "action": { "type": "string", "enum": [ "accept", "decline" ] }, "csrf": { "type": "string", "minLength": 1, "maxLength": 512 }, "attestation": { "type": "boolean", "enum": [ true ] } }, "required": [ "token", "action", "csrf", "attestation" ], "additionalProperties": false }, "GuardianPortalContext": { "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "enum": [ "valid" ] }, "child_account_status": { "type": "string", "enum": [ "active", "held", "blocked" ] }, "registered_at": { "type": "string", "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "data_categories": { "type": "array", "items": { "type": "string" } }, "consent_receipt": { "type": "object", "properties": { "consented_at": { "type": "string", "format": "date-time" }, "lawful_basis": { "type": "string" }, "purposes": { "type": "array", "items": { "type": "string" } }, "data_categories": { "type": "array", "items": { "type": "string" } }, "retention": { "type": "string" }, "controller": { "type": "string" }, "withdrawal_available": { "type": "boolean", "enum": [ true ] }, "consent_method": { "type": "string", "enum": [ "email", "eudi_wallet" ] } }, "required": [ "consented_at", "lawful_basis", "purposes", "data_categories", "retention", "controller", "withdrawal_available", "consent_method" ], "additionalProperties": false }, "controller_name": { "type": "string" }, "csrf": { "type": "string", "minLength": 1, "maxLength": 512 }, "available_actions": { "type": "array", "items": { "type": "string", "enum": [ "withdraw", "export", "delete" ] } }, "confirm_token": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "state", "child_account_status", "registered_at", "last_login_at", "data_categories", "consent_receipt", "controller_name", "csrf", "available_actions" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "invalid" ] } }, "required": [ "state" ], "additionalProperties": false } ] }, "GuardianManagementMutate": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 512 }, "action": { "type": "string", "enum": [ "withdraw", "export", "delete" ] }, "csrf": { "type": "string", "minLength": 1, "maxLength": 512 }, "confirm_nonce": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "token", "action", "csrf" ], "additionalProperties": false }, "GuardianManagementLinkRequest": { "type": "object", "properties": { "child_email": { "type": "string", "maxLength": 254, "format": "email" }, "guardian_email": { "type": "string", "maxLength": 254, "format": "email" } }, "required": [ "child_email", "guardian_email" ], "additionalProperties": false }, "UserEmailOtpRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "mode": { "type": "string", "enum": [ "login", "login_or_create" ], "default": "login" }, "oauth_params": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "response_type": { "type": "string" }, "code_challenge": { "type": "string" }, "code_challenge_method": { "type": "string" }, "scope": { "type": "string" }, "state": { "type": "string" }, "nonce": { "type": "string" }, "resource": { "type": "string" } }, "required": [ "client_id", "redirect_uri" ] }, "captcha_token": { "type": "string" } }, "required": [ "email" ] }, "UserEmailOtpVerifyRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "resume_binding": { "type": "string", "maxLength": 64 } }, "required": [ "email", "code" ] }, "UserSmsOtpRequest": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 5 }, "mode": { "type": "string", "enum": [ "login", "login_or_create" ], "default": "login" }, "channel": { "type": "string", "enum": [ "sms" ], "default": "sms" }, "oauth_params": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "response_type": { "type": "string" }, "code_challenge": { "type": "string" }, "code_challenge_method": { "type": "string" }, "scope": { "type": "string" }, "state": { "type": "string" }, "nonce": { "type": "string" }, "resource": { "type": "string" } }, "required": [ "client_id", "redirect_uri" ] } }, "required": [ "phone" ] }, "UserSmsOtpVerifyRequest": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 5 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "resume_binding": { "type": "string", "maxLength": 64 } }, "required": [ "phone", "code" ] }, "PhoneVerifyRequest": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 5 } }, "required": [ "phone" ] }, "PhoneVerifyConfirmRequest": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 5 }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "phone", "code" ] }, "SmsTestRequest": { "type": "object", "properties": { "tenantSlug": { "type": "string", "minLength": 1 }, "phone": { "type": "string" } }, "required": [ "tenantSlug", "phone" ] }, "MagicLinkRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address", "example": "user@example.com" } }, "required": [ "email" ] }, "MagicLinkVerifyRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "Magic link token" } }, "required": [ "token" ] }, "DashboardLoginRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address", "example": "admin@example.com" }, "password": { "type": "string", "minLength": 8, "maxLength": 128, "description": "Password" } }, "required": [ "email", "password" ] }, "DashboardReauthResponse": { "type": "object", "properties": { "verified_at": { "type": "string", "example": "2026-05-13T10:15:00.000Z" } }, "required": [ "verified_at" ] }, "DashboardReauthRequest": { "type": "object", "properties": { "password": { "type": "string", "minLength": 8, "maxLength": 128, "description": "Current account password" } }, "required": [ "password" ] }, "GoogleSessionRequest": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1, "description": "Exchange JWT from Google OAuth callback" }, "tenant_slug": { "type": [ "string", "null" ], "minLength": 1, "description": "Tenant slug for cross-tenant verification" } }, "required": [ "access_token", "tenant_slug" ] }, "GitHubSessionRequest": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1, "description": "Exchange JWT from GitHub OAuth callback" }, "tenant_slug": { "type": [ "string", "null" ], "minLength": 1, "description": "Tenant slug for cross-tenant verification" } }, "required": [ "access_token", "tenant_slug" ] }, "MicrosoftSessionRequest": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1, "description": "Exchange JWT from Microsoft OAuth callback" }, "tenant_slug": { "type": [ "string", "null" ], "minLength": 1, "description": "Tenant slug for cross-tenant verification" } }, "required": [ "access_token", "tenant_slug" ] }, "AppleSessionRequest": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1, "description": "Exchange JWT from Apple OAuth callback" }, "tenant_slug": { "type": [ "string", "null" ], "minLength": 1, "description": "Tenant slug for cross-tenant verification" } }, "required": [ "access_token", "tenant_slug" ] }, "UpdateTenantSecurityRequest": { "type": "object", "properties": { "mfa_policy": { "type": "string", "enum": [ "optional", "required" ], "description": "Tenant-wide MFA enforcement policy" }, "mfa_grace_period_days": { "type": "integer", "minimum": 3, "maximum": 30, "description": "Days users have to enable MFA before enforcement blocks login (3-30)" }, "block_disposable_emails": { "type": "boolean", "description": "Block registrations from disposable email domains" }, "block_email_subaddresses": { "type": "boolean", "description": "Block registrations with subaddresses like user+tag@" }, "automatic_account_linking_enabled": { "type": "boolean", "description": "When true, a social login whose verified email matches an existing account is automatically linked. Providers that cannot verify email ownership are excluded." }, "sms_otp_enabled": { "type": "boolean", "description": "Tenant-level SMS OTP authentication toggle." }, "sms_otp_monthly_cap": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Per-tenant monthly SMS cap (0-100000, soft ceiling enforced client-side)." }, "byok_twilio_account_sid": { "type": [ "string", "null" ], "pattern": "^AC[a-f0-9]{32}$", "description": "Twilio account SID (AC + 32 hex). Send null to clear." }, "byok_twilio_auth_token": { "type": [ "string", "null" ], "minLength": 32, "maxLength": 128, "description": "Twilio auth token — envelope-encrypted server-side. Send null to clear." }, "byok_twilio_messaging_service_sid": { "type": [ "string", "null" ], "pattern": "^MG[a-f0-9]{32}$", "description": "Twilio Messaging Service SID (MG + 32 hex). Send null to clear." }, "magic_link_enabled": { "type": "boolean", "description": "Tenant-level magic-link login toggle for this tenant's end-users." }, "email_otp_enabled": { "type": "boolean", "description": "Tenant-level email-OTP login toggle for this tenant's end-users." }, "sms_allowed_countries": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" }, "maxItems": 300, "description": "ISO 3166-1 alpha-2 country codes to narrow SMS OTP delivery to (uppercase only — lowercase is rejected, not normalized). `null` or `[]` clears the narrowing back to the full platform allowlist." }, "explicit_account_linking_enabled": { "type": "boolean", "description": "When true, end-users may explicitly request linking an additional social provider to their account. Independent of automatic_account_linking_enabled (passive, verified-email auto-link)." } }, "additionalProperties": false }, "EudiConfigResponse": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "requested_attributes": { "type": "array", "items": { "type": "string", "enum": [ "family_name", "given_name", "birth_date", "nationality", "age_over_16", "age_over_18", "age_over_21", "resident_country", "resident_city", "email", "phone_number" ] } }, "trust_anchors": { "type": "array", "items": { "type": "object", "properties": { "issuer": { "type": "string", "minLength": 1 }, "memberState": { "type": "string", "minLength": 2, "maxLength": 2 }, "allowedAlgs": { "type": "array", "items": { "type": "string", "enum": [ "ES256", "EdDSA" ] }, "minItems": 1 }, "maxAssuranceLevel": { "type": "string", "enum": [ "low", "substantial", "high" ], "default": "high" }, "allowedFormats": { "type": "array", "items": { "type": "string", "enum": [ "dc+sd-jwt", "mso_mdoc" ] }, "minItems": 1 }, "keyResolution": { "oneOf": [ { "type": "object", "properties": { "method": { "type": "string", "enum": [ "jwks_uri" ] }, "jwksUri": { "type": "string", "format": "uri" } }, "required": [ "method", "jwksUri" ] }, { "type": "object", "properties": { "method": { "type": "string", "enum": [ "did_web" ] }, "did": { "type": "string", "pattern": "^did:web:" } }, "required": [ "method", "did" ] }, { "type": "object", "properties": { "method": { "type": "string", "enum": [ "x5c" ] }, "x5cRoots": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } }, "required": [ "method", "x5cRoots" ] } ] }, "displayName": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "issuer", "allowedAlgs", "allowedFormats", "keyResolution" ] } }, "required_assurance_floor": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "enum": [ "aal", "eidas" ] }, "value": { "type": "string", "minLength": 1 } }, "required": [ "kind", "value" ] }, "purpose": { "type": [ "string", "null" ] }, "on_status_unavailable": { "type": "string", "enum": [ "reject", "accept_with_cache", "accept_unverified" ] }, "max_status_staleness_seconds": { "type": "integer" }, "updated_at": { "type": "string" } }, "required": [ "enabled", "requested_attributes", "trust_anchors", "required_assurance_floor", "purpose", "on_status_unavailable", "max_status_staleness_seconds", "updated_at" ] }, "UpdateTenantEudiConfig": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "requested_attributes": { "type": "array", "items": { "type": "string", "enum": [ "family_name", "given_name", "birth_date", "nationality", "age_over_16", "age_over_18", "age_over_21", "resident_country", "resident_city", "email", "phone_number" ] }, "minItems": 1 }, "trust_anchors": { "type": "array", "items": { "type": "object", "properties": { "issuer": { "type": "string", "minLength": 1 }, "memberState": { "type": "string", "minLength": 2, "maxLength": 2 }, "allowedAlgs": { "type": "array", "items": { "type": "string", "enum": [ "ES256", "EdDSA" ] }, "minItems": 1 }, "maxAssuranceLevel": { "type": "string", "enum": [ "low", "substantial", "high" ], "default": "high" }, "allowedFormats": { "type": "array", "items": { "type": "string", "enum": [ "dc+sd-jwt", "mso_mdoc" ] }, "minItems": 1 }, "keyResolution": { "oneOf": [ { "type": "object", "properties": { "method": { "type": "string", "enum": [ "jwks_uri" ] }, "jwksUri": { "type": "string", "format": "uri" } }, "required": [ "method", "jwksUri" ] }, { "type": "object", "properties": { "method": { "type": "string", "enum": [ "did_web" ] }, "did": { "type": "string", "pattern": "^did:web:" } }, "required": [ "method", "did" ] }, { "type": "object", "properties": { "method": { "type": "string", "enum": [ "x5c" ] }, "x5cRoots": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } }, "required": [ "method", "x5cRoots" ] } ] }, "displayName": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "issuer", "allowedAlgs", "allowedFormats", "keyResolution" ] }, "default": [] }, "required_assurance_floor": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "enum": [ "aal", "eidas" ] }, "value": { "type": "string", "minLength": 1 } }, "default": null, "required": [ "kind", "value" ] }, "purpose": { "type": [ "string", "null" ], "maxLength": 300, "default": null }, "on_status_unavailable": { "type": "string", "enum": [ "reject", "accept_with_cache", "accept_unverified" ], "default": "accept_with_cache" }, "max_status_staleness_seconds": { "type": "integer", "minimum": 0, "maximum": 86400, "default": 3600 } }, "required": [ "enabled" ] }, "EudiInitiateResponse": { "type": "object", "properties": { "state": { "type": "string", "description": "Correlation handle for the result poll." }, "request_object": { "type": "string", "description": "The signed JAR request object (compact JWS)." }, "response_uri": { "type": "string", "description": "Where the wallet POSTs the encrypted response." }, "expires_at": { "type": "string", "example": "2026-05-22T10:05:00.000Z" } }, "required": [ "state", "request_object", "response_uri", "expires_at" ] }, "EudiResultResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "consumed", "expired", "not_found" ] }, "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "integer" } }, "required": [ "status" ] }, "EudiAgeVerificationInitiateResponse": { "type": "object", "properties": { "state": { "type": "string", "description": "Correlation handle for the result poll." }, "request_object": { "type": "string", "description": "The signed JAR request object (compact JWS)." }, "response_uri": { "type": "string", "description": "Where the wallet POSTs the encrypted response." }, "expires_at": { "type": "string", "example": "2026-06-02T10:05:00.000Z" } }, "required": [ "state", "request_object", "response_uri", "expires_at" ] }, "EudiAgeVerificationResultResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "determined", "fallback", "expired", "not_found" ], "description": "pending = awaiting wallet; determined = age verified (use the token); fallback = use the date-of-birth field; expired/not_found = re-initiate." }, "age_verification_token": { "type": "string" } }, "required": [ "status" ] }, "EudiAgeConfigResponse": { "type": "object", "properties": { "age_verification_enabled": { "type": "boolean" }, "supported_member_states": { "type": "array", "items": { "type": "string" } }, "threshold_supported": { "type": "boolean" }, "updated_at": { "type": "string" } }, "required": [ "age_verification_enabled", "supported_member_states", "threshold_supported", "updated_at" ] }, "UpdateEudiAgeConfig": { "type": "object", "properties": { "age_verification_enabled": { "type": "boolean" }, "supported_member_states": { "type": "array", "items": { "type": "string", "enum": [ "PL", "DE", "FR", "IE" ] }, "default": [] } }, "required": [ "age_verification_enabled" ] }, "PutEmailDomainsRequest": { "type": "object", "properties": { "allowlist": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "maxItems": 100, "default": [] }, "blocklist": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "maxItems": 100, "default": [] } } }, "UpdateTenantAnonymousSettingsRequest": { "type": "object", "properties": { "anonymous_signins_enabled": { "type": "boolean" }, "anonymous_user_ttl_days": { "type": "integer", "minimum": 1, "maximum": 180 } } }, "UpdateTenantPasskeyDomainRequest": { "type": "object", "properties": { "passkey_rp_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 253, "pattern": "^[a-z0-9.-]+$" } }, "required": [ "passkey_rp_id" ] }, "RevokeMyAgentResponse": { "type": "object", "properties": { "agent_client_id": { "type": "string", "description": "The agent client this revocation applies to" }, "revoked_at": { "type": "string", "description": "RFC 3339 timestamp of the revocation (unchanged on a repeat call)" }, "reason": { "type": "string", "description": "Recorded reason for the revocation" } }, "required": [ "agent_client_id", "revoked_at", "reason" ] }, "RestoreMyAgentResponse": { "type": "object", "properties": { "agent_client_id": { "type": "string", "description": "The agent client this restoration applies to" }, "restored_at": { "type": "string", "description": "RFC 3339 timestamp of the restoration (the CURRENT time on a no-op)" }, "newly_restored": { "type": "boolean", "description": "false when the agent was not revoked — the call is idempotent and fires no second audit event" }, "still_blocked_by": { "type": "string", "enum": [ "tenant" ], "description": "Present only when the restoration succeeded but the agent remains blocked by an authority the user cannot lift. Absent means no residual block." } }, "required": [ "agent_client_id", "restored_at", "newly_restored" ] }, "LoginRequiredResponse": { "type": "object", "properties": { "login_required": { "type": "boolean", "enum": [ true ] }, "authorize_url": { "type": "string", "example": "https://example.com/oauth/authorize?response_type=code&client_id=abc" } }, "required": [ "login_required", "authorize_url" ] }, "ConsentRequiredResponse": { "type": "object", "properties": { "consent_required": { "type": "boolean", "enum": [ true ] }, "client": { "type": "object", "properties": { "name": { "type": "string", "example": "My Web App" }, "description": { "type": "string", "example": "A third-party application" }, "logo_url": { "type": "string", "example": "https://example.com/logo.png" }, "verification": { "type": "string", "enum": [ "first_party", "attested", "unverified" ], "example": "unverified" }, "registered_seconds_ago": { "type": "integer", "example": 240 } }, "required": [ "name", "verification", "registered_seconds_ago" ] }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "read", "write" ] }, "new_scopes": { "type": "array", "items": { "type": "string" }, "example": [ "sso:write" ] }, "unchanged_scopes": { "type": "array", "items": { "type": "string" }, "example": [ "openid", "email" ] }, "custom_scopes": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "example": "acme:invoices.read" }, "display_name": { "type": "string", "example": "Read your invoices" }, "description": { "type": "string", "example": "Lets Acme read invoices you issued." } }, "required": [ "scope", "display_name" ] }, "description": "Tenant-defined scope copy for the scopes in this request" }, "is_re_consent": { "type": "boolean", "example": true }, "change_reason": { "type": "string", "example": "We now sync your calendar." }, "resources": { "type": "array", "items": { "type": "string" }, "example": [ "https://api.third-party.example" ] }, "new_resources": { "type": "array", "items": { "type": "string" }, "example": [ "https://api.third-party.example" ] }, "resource": { "type": "string", "example": "https://api.third-party.example" }, "resource_commitment": { "type": "string", "example": "1752424800:1752425700:9f…" }, "redirect_uri": { "type": "string", "example": "https://example.com/callback" }, "state": { "type": "string", "example": "xyz123" }, "client_id": { "type": "string", "example": "client_abc123" }, "code_challenge": { "type": "string", "example": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM" }, "code_challenge_method": { "type": "string", "enum": [ "S256" ] }, "response_type": { "type": "string", "enum": [ "code" ] }, "scope": { "type": "string", "example": "read write" }, "nonce": { "type": "string", "example": "n-0S6_WzA2Mj" }, "agent_scopes": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "example": "mcp:tools:read" } }, "required": [ "scope" ] }, "description": "Agent capabilities offered for individual approval on this request. Each entry is selected separately; approving none is a valid decision. Always present; an empty array means no capability was offered on this request." }, "agent_revoked": { "type": "boolean", "enum": [ true ], "description": "Present only when the signed-in user currently blocks this application from acting on their behalf. Capabilities cannot be granted while it stands." }, "resource_catalog_scopes": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "example": "acme:calendar:read" }, "display_metadata": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "i18n_key" ] }, "i18n_key": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "kind", "i18n_key" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "locale_text" ] }, "locale_text": { "type": "object", "properties": { "en": { "type": "string", "minLength": 1, "maxLength": 256 }, "pl": { "type": "string", "minLength": 1, "maxLength": 256 }, "de": { "type": "string", "minLength": 1, "maxLength": 256 }, "fr": { "type": "string", "minLength": 1, "maxLength": 256 }, "es": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "en", "pl", "de", "fr", "es" ], "additionalProperties": false } }, "required": [ "kind", "locale_text" ], "additionalProperties": false } ] } }, "required": [ "scope", "display_metadata" ] }, "description": "Resource-catalog scopes registered by the requested resource's own owner, eligible for individual approval. Distinct from agent_scopes (the platform's own mcp:* tiers) and from custom_scopes (a tenant's user-flow custom scopes) — always present, [] when the resource has none." } }, "required": [ "consent_required", "client", "scopes", "new_scopes", "unchanged_scopes", "custom_scopes", "is_re_consent", "resources", "new_resources", "redirect_uri", "state", "client_id", "code_challenge", "code_challenge_method", "response_type", "agent_scopes", "resource_catalog_scopes" ] }, "OAuthErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_request" }, "error_description": { "type": "string", "example": "Unknown client_id" } }, "required": [ "error" ] }, "OAuthClientRegistrationResponse": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_id_issued_at": { "type": "number" }, "client_secret": { "type": "string" }, "client_secret_expires_at": { "type": "number" }, "client_name": { "type": "string" }, "grant_types": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } }, "registration_access_token": { "type": "string" }, "registration_client_uri": { "type": "string" } }, "required": [ "client_id", "client_id_issued_at", "grant_types", "scope", "token_endpoint_auth_method" ] }, "OAuthDeviceApproveResponse": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approved" ] }, "expires_at": { "type": "string", "example": "2026-04-28T12:30:00.000Z" } }, "required": [ "status", "expires_at" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "resource_confirmation_required" ] }, "resource": { "type": "string", "example": "https://api.third-party.example/mcp" }, "resource_host": { "type": "string", "example": "api.third-party.example" } }, "required": [ "status", "resource", "resource_host" ] } ] }, "OAuthDeviceApproveRequest": { "type": "object", "properties": { "user_code": { "type": "string", "minLength": 8, "maxLength": 9, "example": "ABCD-2345" }, "confirm_resource": { "type": "boolean" }, "confirmed_resource": { "type": "string" } }, "required": [ "user_code" ], "additionalProperties": false }, "OAuthDeviceDenyResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "denied" ] }, "denied_at": { "type": "string" } }, "required": [ "status", "denied_at" ] }, "OAuthDeviceDenyRequest": { "type": "object", "properties": { "user_code": { "type": "string", "minLength": 8, "maxLength": 9, "example": "ABCD-2345" } }, "required": [ "user_code" ], "additionalProperties": false }, "DiscordSessionRequest": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1, "description": "Exchange JWT from Discord OAuth callback" }, "tenant_slug": { "type": [ "string", "null" ], "minLength": 1, "description": "Tenant slug for cross-tenant verification" } }, "required": [ "access_token", "tenant_slug" ] }, "FacebookSessionRequest": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1, "description": "Exchange JWT from Facebook OAuth callback" }, "tenant_slug": { "type": [ "string", "null" ], "minLength": 1, "description": "Tenant slug for cross-tenant verification" } }, "required": [ "access_token", "tenant_slug" ] }, "SlackSessionRequest": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1, "description": "Exchange JWT from Slack OAuth callback" }, "tenant_slug": { "type": [ "string", "null" ], "minLength": 1, "description": "Tenant slug for cross-tenant verification" } }, "required": [ "access_token", "tenant_slug" ] }, "TwitterSessionRequest": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1, "description": "Exchange JWT from Twitter/X OAuth callback" }, "tenant_slug": { "type": [ "string", "null" ], "minLength": 1, "description": "Tenant slug for cross-tenant verification" } }, "required": [ "access_token", "tenant_slug" ] }, "GitlabSessionRequest": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1, "description": "Exchange JWT from GitLab OAuth callback" }, "tenant_slug": { "type": [ "string", "null" ], "minLength": 1, "description": "Tenant slug for cross-tenant verification" } }, "required": [ "access_token", "tenant_slug" ] }, "LinkedinSessionRequest": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1, "description": "Exchange JWT from LinkedIn OAuth callback" }, "tenant_slug": { "type": [ "string", "null" ], "minLength": 1, "description": "Tenant slug for cross-tenant verification" } }, "required": [ "access_token", "tenant_slug" ] }, "MeOrgMembership": { "type": "object", "properties": { "org_id": { "type": "string" }, "org_slug": { "type": "string" }, "org_name": { "type": "string" }, "org_role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "membership_public_metadata": {}, "expires_at": { "type": "string" } }, "required": [ "org_id", "org_slug", "org_name", "org_role" ] }, "MePendingOrgInvitation": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "org_slug": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "expires_at": { "type": "string" } }, "required": [ "id", "org_id", "org_name", "org_slug", "role", "expires_at" ] }, "DashboardImpersonateEndUserResponse": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIs..." }, "jti": { "type": "string", "format": "uuid", "example": "5f1e7a90-e3ea-4d2c-91cd-9b0a3a09d5b1" }, "expires_at": { "type": "string", "example": "2026-04-25T10:15:00.000Z" } }, "required": [ "token", "jti", "expires_at" ] }, "DashboardImpersonateEndUserRequest": { "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 320, "example": "alice@acme-corp.com" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500, "example": "Reproducing customer-reported issue ACME-1234 in account-linking flow." } }, "required": [ "email", "reason" ], "additionalProperties": false }, "PulseMetrics": { "type": "object", "properties": { "wat": { "$ref": "#/components/schemas/MetricValue" }, "wau": { "$ref": "#/components/schemas/MetricValue" }, "activation_rate": { "$ref": "#/components/schemas/MetricValue" }, "scaffold_adoption": { "$ref": "#/components/schemas/MetricValue" }, "error_rate": { "$ref": "#/components/schemas/MetricValue" }, "worst_tenant": { "type": [ "object", "null" ], "properties": { "tenant_id": { "type": "string" }, "tenant_name": { "type": "string" }, "error_rate_pct": { "type": "number" } }, "required": [ "tenant_id", "tenant_name", "error_rate_pct" ] }, "tenants_above_threshold": { "type": "object", "properties": { "count": { "type": "number" }, "tenants": { "type": "array", "items": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "tenant_name": { "type": "string" }, "error_rate_pct": { "type": "number" } }, "required": [ "tenant_id", "tenant_name", "error_rate_pct" ] } } }, "required": [ "count", "tenants" ] }, "manual_metrics": { "type": "object", "properties": { "auth_attention_hours_pct": { "$ref": "#/components/schemas/ManualMetric" }, "api_db_maintenance_hours": { "$ref": "#/components/schemas/ManualMetric" }, "founder_energy": { "$ref": "#/components/schemas/ManualMetric" } }, "required": [ "auth_attention_hours_pct", "api_db_maintenance_hours", "founder_energy" ] }, "operational_health": { "type": "object", "properties": { "email_outbox_pending": { "type": "number" }, "email_outbox_failed": { "type": "number" }, "webhook_circuit_breakers_open": { "type": "number" }, "signing_key_days_until_rotation": { "type": [ "number", "null" ] } }, "required": [ "email_outbox_pending", "email_outbox_failed", "webhook_circuit_breakers_open", "signing_key_days_until_rotation" ] }, "computed_at": { "type": "string" } }, "required": [ "wat", "wau", "activation_rate", "scaffold_adoption", "error_rate", "worst_tenant", "tenants_above_threshold", "manual_metrics", "operational_health", "computed_at" ] }, "MetricValue": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "previous_value": { "type": [ "number", "null" ] }, "trend": { "type": "array", "items": { "type": "number" } }, "days_with_data": { "type": "number" }, "low_confidence": { "type": "boolean" }, "target": { "type": "number" }, "status": { "type": "string", "enum": [ "green", "amber", "red", "unknown" ] } }, "required": [ "value", "previous_value", "trend", "days_with_data", "low_confidence", "status" ] }, "ManualMetric": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "value", "updated_at" ] }, "DashboardBlockedIp": { "type": "object", "properties": { "ip": { "type": "string", "example": "192.0.2.1" }, "blocked_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" }, "expires_at": { "type": "string", "example": "2026-03-07T13:00:00.000Z" }, "tenant_count": { "type": "number", "example": 3 } }, "required": [ "ip", "blocked_at", "expires_at", "tenant_count" ] }, "BillingPlanResponse": { "type": "object", "properties": { "billing_enabled": { "type": "boolean" }, "plan": { "type": "string" }, "effective_plan": { "type": "string" }, "trial_active": { "type": "boolean" }, "trial_ends_at": { "type": "string" }, "limits": { "type": "object", "properties": { "mau": { "type": "number" }, "tenants": { "type": "number" }, "api_keys": { "type": "number" }, "webhooks": { "type": "number" }, "oauth_clients": { "type": "number" }, "event_retention_days": { "type": "number" } }, "required": [ "mau", "tenants", "api_keys", "webhooks", "oauth_clients", "event_retention_days" ] }, "features": { "type": "object", "properties": { "audit_package": { "type": "boolean" }, "custom_domain": { "type": "boolean" } }, "required": [ "audit_package", "custom_domain" ] }, "pending_downgrade": { "type": "object", "properties": { "target_plan": { "type": "string" }, "scheduled_at": { "type": "string" }, "effective_at": { "type": "string" } }, "required": [ "target_plan", "scheduled_at", "effective_at" ] }, "subscription_status": { "type": "string" }, "overage_blocks": { "type": "number" }, "billing_interval": { "type": "string" }, "current_period_end": { "type": "string" }, "provider_degraded": { "type": "boolean" } }, "required": [ "billing_enabled", "plan", "effective_plan", "trial_active", "limits", "features", "overage_blocks", "provider_degraded" ] }, "BillingUsageResponse": { "type": "object", "properties": { "plan": { "type": "string" }, "effective_plan": { "type": "string" }, "mau": { "type": "object", "properties": { "current": { "type": "number" }, "limit": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "current", "limit", "percentage" ] }, "warning_threshold": { "type": "string" }, "overage_blocks": { "type": "number" }, "effective_mau_limit": { "type": "number" }, "resources": { "type": "object", "properties": { "api_keys": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" } }, "required": [ "used", "limit" ] }, "webhooks": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" } }, "required": [ "used", "limit" ] }, "oauth_clients": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" } }, "required": [ "used", "limit" ] }, "tenants": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" } }, "required": [ "used", "limit" ] } }, "required": [ "api_keys", "webhooks", "oauth_clients", "tenants" ] } }, "required": [ "plan", "effective_plan", "mau", "overage_blocks", "effective_mau_limit", "resources" ] }, "CheckoutSessionVerifyResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Stripe session lifecycle: open | complete | expired" }, "payment_status": { "type": "string", "description": "Stripe payment status: paid | unpaid | no_payment_required" }, "plan": { "type": [ "string", "null" ], "description": "Purchased plan tier from session metadata, or null" } }, "required": [ "status", "payment_status", "plan" ] }, "BaasConnectionResponse": { "type": "object", "properties": { "connected": { "type": "boolean" }, "onboarding_completed": { "type": "boolean" }, "active": { "type": "boolean" }, "monthly_volume_eur": { "type": "number" }, "monthly_volume_reset_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "connected", "onboarding_completed", "active", "monthly_volume_eur", "monthly_volume_reset_at", "created_at", "updated_at" ] }, "BaasProductResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "created_at", "updated_at" ] }, "BaasPlanResponse": { "type": "object", "properties": { "id": { "type": "string" }, "product_id": { "type": "string" }, "name": { "type": "string" }, "price_cents": { "type": "number" }, "currency": { "type": "string" }, "interval": { "type": "string" }, "trial_days": { "type": [ "number", "null" ] }, "features": { "type": [ "array", "null" ], "items": { "type": "string" } }, "role_id": { "type": [ "string", "null" ] }, "flag_keys": { "type": [ "array", "null" ], "items": { "type": "string" } }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "product_id", "name", "price_cents", "currency", "interval", "trial_days", "features", "role_id", "flag_keys", "active", "created_at", "updated_at" ] }, "BaasSubscriptionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "user_id": { "type": "string" }, "plan_id": { "type": "string" }, "plan_name": { "type": "string" }, "status": { "type": "string" }, "current_period_start": { "type": [ "string", "null" ] }, "current_period_end": { "type": [ "string", "null" ] }, "trial_end": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "user_id", "plan_id", "plan_name", "status", "current_period_start", "current_period_end", "trial_end", "cancelled_at", "created_at", "updated_at" ] }, "BaasPublicPlanResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price_cents": { "type": "number" }, "currency": { "type": "string" }, "interval": { "type": "string" }, "trial_days": { "type": [ "number", "null" ] }, "features": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "id", "name", "price_cents", "currency", "interval", "trial_days", "features" ] }, "BillingSmokeStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "issued", "failed", "not_found" ], "description": "issued: Fakturownia invoice created (PASS). not_found: bridge not yet processed. failed: terminal bridge error. pending: unused (reserved)." }, "fakturownia_external_id": { "type": [ "string", "null" ], "description": "Fakturownia external invoice ID from stripe_fakturownia_invoice_map, or null." }, "gov_status": { "type": [ "string", "null" ], "description": "Raw KSeF gov_status from bridge map (server_error = DEMO expected; not a failure)." }, "email_outbox_count": { "type": "integer", "description": "Number of email_outbox rows whose idempotency_key ends with the stripe_invoice_id." }, "last_error": { "type": [ "string", "null" ], "description": "Error message from billing_audit_events.payload.error_message on status=failed, null otherwise." } }, "required": [ "status", "fakturownia_external_id", "gov_status", "email_outbox_count", "last_error" ] }, "StagingCheckoutSessionResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Stripe-hosted Checkout session URL — client redirects browser here" } }, "required": [ "url" ] }, "SwitchOrgResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "org_role": { "type": [ "string", "null" ] }, "org_slug": { "type": [ "string", "null" ] } }, "required": [ "access_token", "expires_in", "token_type", "org_id", "org_role", "org_slug" ] }, "SwitchOrgRequest": { "type": "object", "properties": { "org_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Organization ID to switch to, or null to clear org context" } }, "required": [ "org_id" ] }, "OrgResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "enrollment_mode": { "type": "string", "enum": [ "invite_only", "public", "public_with_approval" ] }, "member_count": { "type": "number" }, "created_by": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "logo_url": { "type": "string" }, "metadata": {}, "allowed_email_domains": { "type": "array", "items": { "type": "string" } }, "max_members_override": { "type": [ "number", "null" ] } }, "required": [ "id", "name", "slug", "enrollment_mode", "member_count", "created_by", "created_at", "updated_at" ] }, "OrgMemberResponse": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "user_id": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "status": { "type": "string", "enum": [ "active", "suspended" ] }, "joined_at": { "type": "string" }, "membership_expires_at": { "type": "string" }, "membership_public_metadata": {} }, "required": [ "id", "org_id", "user_id", "role", "status", "joined_at" ] }, "OrgJoinRequest": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "user_id": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "decided_at": { "type": "string" }, "decided_by": { "type": "string" } }, "required": [ "id", "org_id", "user_id", "status", "created_at" ] }, "OrgAuthPolicyResponse": { "type": "object", "properties": { "org_id": { "type": "string" }, "mfa_required": { "type": "boolean" }, "sso_required": { "type": "boolean" }, "allowed_email_domains": { "type": [ "array", "null" ], "items": { "type": "string" } }, "session_timeout_seconds": { "type": [ "integer", "null" ] } }, "required": [ "org_id", "mfa_required", "sso_required", "allowed_email_domains", "session_timeout_seconds" ] }, "UpdateOrgAuthPolicyResponse": { "type": "object", "properties": { "org_id": { "type": "string" }, "mfa_required": { "type": "boolean" }, "sso_required": { "type": "boolean" }, "allowed_email_domains": { "type": [ "array", "null" ], "items": { "type": "string" } }, "session_timeout_seconds": { "type": [ "integer", "null" ] } }, "required": [ "org_id", "mfa_required", "sso_required", "allowed_email_domains", "session_timeout_seconds" ] }, "UpdateOrgAuthPolicyRequest": { "type": "object", "properties": { "mfa_required": { "type": "boolean" }, "sso_required": { "type": "boolean" }, "allowed_email_domains": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 253 }, "maxItems": 50 }, "session_timeout_seconds": { "type": [ "integer", "null" ], "minimum": 300, "maximum": 43200 } } }, "UserOrgListItem": { "type": "object", "properties": { "org_id": { "type": "string" }, "org_slug": { "type": "string" }, "org_name": { "type": "string" }, "org_role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "membership_public_metadata": {}, "expires_at": { "type": "string" } }, "required": [ "org_id", "org_slug", "org_name", "org_role" ] } }, "parameters": {} }, "paths": { "/v1/health": { "get": { "tags": [ "System" ], "summary": "Health check", "operationId": "getHealth", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] } } } } } } }, "/v1/legal/{type}": { "get": { "tags": [ "Legal" ], "summary": "Get legal page", "operationId": "getLegalPage", "parameters": [ { "schema": { "type": "string", "enum": [ "privacy-policy", "terms-of-service", "cookie-policy", "dpa", "complaint-procedure", "provider-identification", "accessibility-statement" ] }, "required": true, "name": "type", "in": "path" }, { "schema": { "type": "string", "enum": [ "en", "pl" ], "default": "en" }, "required": false, "name": "lang", "in": "query" } ], "responses": { "200": { "description": "Legal page HTML", "content": { "text/html": { "schema": { "type": "string" } } } }, "304": { "description": "Not Modified" }, "404": { "description": "Legal page not found" }, "503": { "description": "Legal pages not available" } } } }, "/v1/onboarding/signup": { "post": { "tags": [ "Onboarding" ], "summary": "Create account, tenant, and initial API key atomically", "operationId": "postOnboardingSignup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingSignupRequest" } } } }, "responses": { "201": { "description": "Account created (or email already exists — identical shape for both, no enumeration)", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "example": "01961234-5678-7abc-8def-0123456789ab" }, "tenant_id": { "type": "string", "example": "01961234-5678-7abc-8def-0123456789cd" }, "api_key_id": { "type": "string", "example": "01961234-5678-7abc-8def-0123456789ef" }, "api_key_raw": { "type": "string", "example": "akm_live_XXXXXXXXXXXXXXXXXXXXXXXXXXX" }, "test_api_key_id": { "type": "string", "example": "01961234-5678-7abc-8def-012345678900" }, "test_api_key_raw": { "type": "string", "example": "akm_test_XXXXXXXXXXXXXXXXXXXXXXXXXXX" }, "email": { "type": "string", "example": "founder@example.com" } }, "required": [ "user_id", "tenant_id", "api_key_id", "api_key_raw", "test_api_key_id", "test_api_key_raw", "email" ] } } } }, "400": { "description": "Bot challenge failed (Turnstile)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Validation error (missing consent, short password)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited (per-IP or global signup limit)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/.well-known/jwks.json": { "get": { "tags": [ "System" ], "summary": "JSON Web Key Set for token verification", "operationId": "getJwks", "responses": { "200": { "description": "JWKS containing current public signing key(s)", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "type": "string", "description": "Key type", "example": "RSA" }, "kid": { "type": "string", "description": "Key ID", "example": "rakomi-key-1" }, "alg": { "type": "string", "description": "Algorithm", "example": "RS256" }, "use": { "type": "string", "description": "Key usage", "example": "sig" }, "n": { "type": "string", "description": "RSA modulus (Base64url) — RSA keys only" }, "e": { "type": "string", "description": "RSA exponent (Base64url) — RSA keys only", "example": "AQAB" }, "crv": { "type": "string", "description": "EC curve — EC keys only", "example": "P-256" }, "x": { "type": "string", "description": "EC x coordinate (Base64url) — EC keys only" }, "y": { "type": "string", "description": "EC y coordinate (Base64url) — EC keys only" } }, "required": [ "kty", "kid", "alg", "use" ], "additionalProperties": {} }, "description": "Array of JSON Web Keys" }, "revocation_epoch": { "type": "integer", "exclusiveMinimum": 0, "description": "Unix timestamp (seconds) of last emergency token revocation. Tokens with iat < this value should be rejected." } }, "required": [ "keys" ] } } } } } } }, "/.well-known/webauthn": { "get": { "tags": [ "System" ], "summary": "WebAuthn Relying Party origins (RFC-style well-known)", "operationId": "getWellKnownWebauthn", "responses": { "200": { "description": "JSON body listing allowed WebAuthn origins for the fallback RP ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "origins": { "type": "array", "items": { "type": "string" } } }, "required": [ "origins" ] } } } } } } }, "/.well-known/did.json": { "get": { "tags": [ "VC Issuer" ], "summary": "did:web DID document for rakomi.com", "operationId": "getWellKnownDidJson", "responses": { "200": { "description": "did:web:rakomi.com DID document", "content": { "application/did+json": { "schema": { "type": "object", "properties": { "@context": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "verificationMethod": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "assertionMethod": { "type": "array", "items": { "type": "string" } }, "service": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "@context", "id", "verificationMethod", "assertionMethod", "service" ], "additionalProperties": {} } } } }, "503": { "description": "Issuer signing keys not configured" } } } }, "/.well-known/oauth-protected-resource": { "get": { "tags": [ "System" ], "summary": "OAuth 2.0 Protected Resource Metadata (RFC 9728)", "operationId": "getWellKnownOauthProtectedResource", "responses": { "200": { "description": "RFC 9728 protected resource metadata document", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string", "description": "RFC 9728 §2 — canonical resource identifier (the `aud` MCP tokens carry)", "example": "https://mcp.rakomi.com" }, "authorization_servers": { "type": "array", "items": { "type": "string" }, "description": "RFC 9728 §2 — the AS issuer(s) that protect this resource. Always an array (plural).", "example": [ "https://api.rakomi.com" ] }, "scopes_supported": { "type": "array", "items": { "type": "string" }, "description": "RFC 9728 §2 — MCP scope namespace this resource accepts", "example": [ "mcp:tools:read", "mcp:tools:write", "mcp:tools:destructive" ] }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" }, "description": "RFC 6750 §2.1 — Authorization request header is the only accepted bearer method", "example": [ "header" ] }, "dpop_signing_alg_values_supported": { "type": "array", "items": { "type": "string" }, "description": "RFC 9449 §5.1 — DPoP proof-signing algorithms this resource accepts (sender-constraining is permitted, not required)", "example": [ "ES256", "EdDSA" ] } }, "required": [ "resource", "authorization_servers", "scopes_supported", "bearer_methods_supported", "dpop_signing_alg_values_supported" ], "additionalProperties": {} } } } } } } }, "/.well-known/openid-credential-issuer": { "get": { "tags": [ "VC Issuer" ], "summary": "OpenID4VCI issuer metadata", "operationId": "getWellKnownOpenidCredentialIssuer", "responses": { "200": { "description": "OpenID4VCI 1.0 issuer metadata document", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential_issuer": { "type": "string", "format": "uri" }, "credential_endpoint": { "type": "string", "format": "uri" }, "token_endpoint": { "type": "string", "format": "uri" }, "jwks_uri": { "type": "string", "format": "uri" }, "trust_framework": { "type": "string" }, "trust_framework_uri": { "type": "string", "format": "uri" }, "credential_configurations_supported": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} } } }, "required": [ "credential_issuer", "credential_endpoint", "token_endpoint", "jwks_uri", "trust_framework", "trust_framework_uri", "credential_configurations_supported" ], "additionalProperties": {} } } } } } } }, "/.well-known/sdk-support.json": { "get": { "tags": [ "System" ], "summary": "SDK Support & EOL policy (>=5-year / 60-month support per MAJOR, N & N-1 parallel)", "operationId": "getWellKnownSdkSupport", "responses": { "200": { "description": "Machine-readable SDK support-window policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkSupportPolicy" } } } }, "404": { "description": "Endpoint disabled in this environment (SDK_SUPPORT_ENDPOINT_ENABLED off)" }, "503": { "description": "SECURITY-SUPPORT.json missing or schema-invalid (fails closed — never serves garbage)" } } } }, "/.well-known/ssf-configuration": { "get": { "tags": [ "SSF" ], "summary": "OpenID SSF discovery metadata", "operationId": "getWellKnownSsfConfiguration", "responses": { "200": { "description": "OpenID SSF 1.0 configuration document", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string", "format": "uri" }, "jwks_uri": { "type": "string", "format": "uri" }, "configuration_endpoint": { "type": "string", "format": "uri" }, "status_endpoint": { "type": "string", "format": "uri" }, "add_subject_endpoint": { "type": "string", "format": "uri" }, "remove_subject_endpoint": { "type": "string", "format": "uri" }, "verification_endpoint": { "type": "string", "format": "uri" }, "delivery_methods_supported": { "type": "array", "items": { "type": "string" } }, "critical_subject_members": { "type": "array", "items": { "type": "string" } }, "authorization_schemes": { "type": "array", "items": { "type": "object", "properties": { "spec_urn": { "type": "string" } }, "required": [ "spec_urn" ] } }, "spec_version": { "type": "string" } }, "required": [ "issuer", "jwks_uri", "configuration_endpoint", "status_endpoint", "add_subject_endpoint", "remove_subject_endpoint", "verification_endpoint", "delivery_methods_supported", "authorization_schemes", "spec_version" ], "additionalProperties": {} } } } } } } }, "/.well-known/risc-configuration": { "get": { "tags": [ "SSF" ], "summary": "OpenID RISC discovery metadata (alias of SSF discovery)", "operationId": "getWellKnownRiscConfiguration", "responses": { "200": { "description": "OpenID RISC discovery document (same payload as SSF)", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string", "format": "uri" }, "jwks_uri": { "type": "string", "format": "uri" }, "configuration_endpoint": { "type": "string", "format": "uri" }, "status_endpoint": { "type": "string", "format": "uri" }, "add_subject_endpoint": { "type": "string", "format": "uri" }, "remove_subject_endpoint": { "type": "string", "format": "uri" }, "verification_endpoint": { "type": "string", "format": "uri" }, "delivery_methods_supported": { "type": "array", "items": { "type": "string" } }, "critical_subject_members": { "type": "array", "items": { "type": "string" } }, "authorization_schemes": { "type": "array", "items": { "type": "object", "properties": { "spec_urn": { "type": "string" } }, "required": [ "spec_urn" ] } }, "spec_version": { "type": "string" } }, "required": [ "issuer", "jwks_uri", "configuration_endpoint", "status_endpoint", "add_subject_endpoint", "remove_subject_endpoint", "verification_endpoint", "delivery_methods_supported", "authorization_schemes", "spec_version" ], "additionalProperties": {} } } } } } } }, "/ssf/receiver/events": { "post": { "tags": [ "SSF" ], "summary": "RFC 8935 SET push delivery target", "operationId": "postSsfReceiverEvents", "responses": { "202": { "description": "Accepted for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean", "enum": [ true ] } }, "required": [ "accepted" ] } } } }, "400": { "description": "Malformed or unverifiable SET", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } }, "415": { "description": "Unsupported content-type", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } } } } }, "/ssf/streams": { "post": { "tags": [ "SSF" ], "summary": "Create an SSF stream (transmitter side)", "operationId": "createSsfStream", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "method": { "type": "string", "default": "https://schemas.openid.net/secevent/risc/delivery-method/push" }, "endpoint_url": { "type": "string", "format": "uri" }, "authorization_header": { "type": "string" } }, "required": [ "endpoint_url" ] }, "events_requested": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "audience": { "type": "string", "minLength": 1 } }, "required": [ "delivery", "events_requested", "audience" ] } } } }, "responses": { "201": { "description": "Stream created", "content": { "application/json": { "schema": { "type": "object", "properties": { "stream_id": { "type": "string" }, "role": { "type": "string", "enum": [ "transmitter", "receiver" ] }, "issuer": { "type": "string" }, "delivery_method": { "type": "string" }, "endpoint_url": { "type": [ "string", "null" ] }, "audience": { "type": "string" }, "events_requested": { "type": "array", "items": { "type": "string" } }, "events_delivered": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } }, "required": [ "stream_id", "role", "issuer", "delivery_method", "endpoint_url", "audience", "events_requested", "events_delivered", "status" ] } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } } } }, "get": { "tags": [ "SSF" ], "summary": "List SSF streams for the calling tenant", "operationId": "listSsfStreams", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "streams": { "type": "array", "items": { "type": "object", "properties": { "stream_id": { "type": "string" }, "role": { "type": "string", "enum": [ "transmitter", "receiver" ] }, "issuer": { "type": "string" }, "delivery_method": { "type": "string" }, "endpoint_url": { "type": [ "string", "null" ] }, "audience": { "type": "string" }, "events_requested": { "type": "array", "items": { "type": "string" } }, "events_delivered": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } }, "required": [ "stream_id", "role", "issuer", "delivery_method", "endpoint_url", "audience", "events_requested", "events_delivered", "status" ] } } }, "required": [ "streams" ] } } } } } } }, "/ssf/streams/{id}": { "get": { "tags": [ "SSF" ], "summary": "Get a stream", "operationId": "getSsfStream", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "stream_id": { "type": "string" }, "role": { "type": "string", "enum": [ "transmitter", "receiver" ] }, "issuer": { "type": "string" }, "delivery_method": { "type": "string" }, "endpoint_url": { "type": [ "string", "null" ] }, "audience": { "type": "string" }, "events_requested": { "type": "array", "items": { "type": "string" } }, "events_delivered": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } }, "required": [ "stream_id", "role", "issuer", "delivery_method", "endpoint_url", "audience", "events_requested", "events_delivered", "status" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } } } }, "delete": { "tags": [ "SSF" ], "summary": "Delete a stream", "operationId": "deleteSsfStream", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } } } } }, "/ssf/streams/{id}/status": { "get": { "tags": [ "SSF" ], "summary": "Get stream status", "operationId": "getSsfStreamStatus", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } } } }, "patch": { "tags": [ "SSF" ], "summary": "Update stream status", "operationId": "patchSsfStreamStatus", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enabled", "paused", "disabled" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } } } } }, "/ssf/streams/{id}/subjects:add": { "post": { "tags": [ "SSF" ], "summary": "Add subject to stream", "operationId": "postSsfSubjectsAdd", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "object", "additionalProperties": {} } }, "required": [ "subject" ] } } } }, "responses": { "204": { "description": "OK" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } } } } }, "/ssf/streams/{id}/subjects:remove": { "post": { "tags": [ "SSF" ], "summary": "Remove subject from stream", "operationId": "postSsfSubjectsRemove", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "object", "additionalProperties": {} } }, "required": [ "subject" ] } } } }, "responses": { "204": { "description": "OK" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } } } } }, "/ssf/streams/{id}/verification": { "post": { "tags": [ "SSF" ], "summary": "Trigger a verification event for the stream", "operationId": "postSsfStreamVerification", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" } } } } } }, "responses": { "204": { "description": "Verification event queued" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "err": { "type": "string" }, "description": { "type": "string" } }, "required": [ "err" ] } } } } } } }, "/vct/{type}/{version}": { "get": { "tags": [ "VC Issuer" ], "summary": "JSON Schema 2020-12 for a credential type", "operationId": "getVctSchema", "parameters": [ { "schema": { "type": "string", "enum": [ "MembershipCredential", "SubscriptionCredential", "VerifiedEmailCredential", "AgeVerificationCredential", "CustomCredential", "consent-receipt" ] }, "required": true, "name": "type", "in": "path" }, { "schema": { "type": "string", "enum": [ "v1" ] }, "required": true, "name": "version", "in": "path" } ], "responses": { "200": { "description": "JSON Schema for the credential type", "content": { "application/schema+json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "404": { "description": "Unknown credential type or version" } } } }, "/v1/credentials/issue": { "post": { "tags": [ "VC Issuer" ], "summary": "Issue a Verifiable Credential (server-to-server)", "operationId": "issueVcCredential", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "credential_type": { "type": "string", "enum": [ "MembershipCredential", "SubscriptionCredential", "VerifiedEmailCredential", "AgeVerificationCredential", "CustomCredential", "ConsentReceiptCredential" ] }, "custom_type_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "claims": { "type": "object", "additionalProperties": {} }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "subject_type": { "type": "string", "enum": [ "user", "agent", "org" ] } }, "required": [ "user_id", "credential_type", "claims" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Credential offer created", "content": { "application/json": { "schema": { "type": "object", "properties": { "jti": { "type": "string" }, "vct": { "type": "string", "format": "uri" }, "status": { "type": "object", "properties": { "idx": { "type": "integer", "minimum": 0 }, "uri": { "type": "string", "format": "uri" } }, "required": [ "idx", "uri" ] }, "credential_offer_uri": { "type": "string" }, "download_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "jti", "vct", "status", "credential_offer_uri", "download_url", "expires_at" ], "additionalProperties": false } } } }, "400": { "description": "Invalid claims", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Issuer disabled / DPIA not acknowledged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/credentials": { "get": { "tags": [ "VC Issuer" ], "summary": "List VCs issued to this tenant", "operationId": "listVcCredentials", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "user_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "credential_type", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "jti": { "type": "string" }, "vct": { "type": "string", "format": "uri" }, "credential_type": { "type": "string", "enum": [ "MembershipCredential", "SubscriptionCredential", "VerifiedEmailCredential", "AgeVerificationCredential", "CustomCredential", "ConsentReceiptCredential" ] }, "custom_type_name": { "type": [ "string", "null" ] }, "user_id": { "type": "string", "format": "uuid" }, "subject_type": { "type": "string", "enum": [ "user", "agent", "org" ] }, "issued_at": { "type": "string", "format": "date-time" }, "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "revocation_reason": { "type": [ "string", "null" ], "enum": [ "key_compromise", "service_terminated", "attribute_change", "user_request", "other", null ] }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "signing_kid": { "type": "string" }, "holder_jkt": { "type": [ "string", "null" ] } }, "required": [ "jti", "vct", "credential_type", "custom_type_name", "user_id", "subject_type", "issued_at", "valid_from", "valid_until", "revoked_at", "revocation_reason", "status", "signing_kid", "holder_jkt" ], "additionalProperties": false } } }, "required": [ "data" ] } } } } } } }, "/v1/credentials/{jti}": { "get": { "tags": [ "VC Issuer" ], "summary": "Get a credential by jti", "operationId": "getVcCredential", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "jti", "in": "path" } ], "responses": { "200": { "description": "Credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "jti": { "type": "string" }, "vct": { "type": "string", "format": "uri" }, "credential_type": { "type": "string", "enum": [ "MembershipCredential", "SubscriptionCredential", "VerifiedEmailCredential", "AgeVerificationCredential", "CustomCredential", "ConsentReceiptCredential" ] }, "custom_type_name": { "type": [ "string", "null" ] }, "user_id": { "type": "string", "format": "uuid" }, "subject_type": { "type": "string", "enum": [ "user", "agent", "org" ] }, "issued_at": { "type": "string", "format": "date-time" }, "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "revocation_reason": { "type": [ "string", "null" ], "enum": [ "key_compromise", "service_terminated", "attribute_change", "user_request", "other", null ] }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "signing_kid": { "type": "string" }, "holder_jkt": { "type": [ "string", "null" ] } }, "required": [ "jti", "vct", "credential_type", "custom_type_name", "user_id", "subject_type", "issued_at", "valid_from", "valid_until", "revoked_at", "revocation_reason", "status", "signing_kid", "holder_jkt" ], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/credentials/{jti}/revoke": { "post": { "tags": [ "VC Issuer" ], "summary": "Revoke a credential (flip status-list bit)", "operationId": "revokeVcCredential", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "jti", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "key_compromise", "service_terminated", "attribute_change", "user_request", "other" ] } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "jti": { "type": "string" }, "revoked_at": { "type": "string", "format": "date-time" }, "status": { "type": "object", "properties": { "idx": { "type": "integer", "minimum": 0 }, "uri": { "type": "string", "format": "uri" }, "list_version": { "type": "integer", "minimum": 0 } }, "required": [ "idx", "uri", "list_version" ] } }, "required": [ "jti", "revoked_at", "status" ], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/credentials/offer/{state}": { "get": { "tags": [ "VC Issuer" ], "summary": "Public credential_offer document (single-use)", "operationId": "getVcCredentialOffer", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "required": true, "name": "state", "in": "path" } ], "responses": { "200": { "description": "OpenID4VCI credential_offer JSON", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "404": { "description": "Unknown offer" }, "410": { "description": "Offer expired" }, "429": { "description": "Rate limited (replay storm or per-IP cap)" } } } }, "/oidc4vci/token": { "post": { "tags": [ "VC Issuer" ], "summary": "OpenID4VCI token endpoint (pre-authorized_code grant)", "operationId": "oidc4vciToken", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:pre-authorized_code" ] }, "pre-authorized_code": { "type": "string", "minLength": 8, "maxLength": 256 }, "client_id": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "grant_type", "pre-authorized_code" ] } } } }, "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer" }, "c_nonce": { "type": "string" }, "c_nonce_expires_in": { "type": "integer" } }, "required": [ "access_token", "token_type", "expires_in", "c_nonce", "c_nonce_expires_in" ] } } } }, "400": { "description": "invalid_grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/oidc4vci/credential": { "post": { "tags": [ "VC Issuer" ], "summary": "OpenID4VCI credential endpoint", "operationId": "oidc4vciCredential", "parameters": [ { "schema": { "type": "string", "pattern": "^Bearer\\s+\\S+" }, "required": true, "name": "authorization", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "vc+sd-jwt", "dc+sd-jwt" ] }, "proof": { "type": "object", "properties": { "proof_type": { "type": "string", "enum": [ "jwt" ] }, "jwt": { "type": "string", "minLength": 1, "maxLength": 8192 } }, "required": [ "proof_type", "jwt" ] } }, "required": [ "format", "proof" ] } } } }, "responses": { "200": { "description": "SD-JWT VC issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "dc+sd-jwt" ] }, "credential": { "type": "string" }, "c_nonce": { "type": "string" }, "c_nonce_expires_in": { "type": "integer" } }, "required": [ "format", "credential", "c_nonce", "c_nonce_expires_in" ] } } } }, "400": { "description": "invalid_proof / invalid_nonce", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "invalid_token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large (RFC 9457 problem-details)" }, "429": { "description": "Rate limited (per-IP storm protection)" } } } }, "/status/sd-jwt/{listId}": { "get": { "tags": [ "VC Issuer" ], "summary": "IETF Token Status List (signed JWS, DEFLATE)", "operationId": "getStatusListSdJwt", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "listId", "in": "path" } ], "responses": { "200": { "description": "JWS envelope (statuslist+jwt)", "content": { "application/json": { "schema": { "type": "object", "properties": { "jws": { "type": "string" } }, "required": [ "jws" ] } } } }, "404": { "description": "Unknown list" } } } }, "/status/bitstring/{listId}": { "get": { "tags": [ "VC Issuer" ], "summary": "W3C BitstringStatusList (signed JSON, GZIP)", "operationId": "getStatusListBitstring", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "listId", "in": "path" } ], "responses": { "200": { "description": "Signed VC envelope", "content": { "application/json": { "schema": { "type": "object", "properties": { "jws": { "type": "string" } }, "required": [ "jws" ] } } } }, "404": { "description": "Unknown list" } } } }, "/verify/{jti}": { "get": { "tags": [ "VC Issuer" ], "summary": "Public consent-receipt verifier (inclusion proof + status + anchor)", "operationId": "verifyConsentReceipt", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "jti", "in": "path" }, { "schema": { "type": "string", "enum": [ "json" ] }, "required": false, "name": "format", "in": "query" } ], "responses": { "200": { "description": "Verification verdict (JSON canonical; HTML when negotiated)", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": {} } } } }, "404": { "description": "Unknown / withheld / disabled — byte-identical body" } } } }, "/v1/auth/step-up/password": { "post": { "tags": [ "Auth" ], "summary": "Issue a short-lived step-up re-auth token after password verify", "operationId": "postAuthStepUpPassword", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepUpPasswordRequest" } } } }, "responses": { "200": { "description": "Step-up token issued — attach via X-Step-Up-Token header for passkey CRUD + register ceremonies", "content": { "application/json": { "schema": { "type": "object", "properties": { "step_up_token": { "type": "string", "example": "abCdEf..." }, "token_type": { "type": "string", "enum": [ "StepUp" ] }, "expires_in": { "type": "number", "example": 300 } }, "required": [ "step_up_token", "token_type", "expires_in" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid password or missing auth", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/step-up/magic-link/initiate": { "post": { "tags": [ "Auth" ], "summary": "Initiate a step-up magic-link to the authenticated user email", "operationId": "postAuthStepUpMagicLinkInitiate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepUpMagicLinkInitiateRequest" } } } }, "responses": { "202": { "description": "Step-up magic link queued for delivery", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "sent" ] }, "email_masked": { "type": "string", "example": "b***@***.com" } }, "required": [ "status", "email_masked" ] } } } }, "400": { "description": "Invalid action_hint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Email delivery temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/step-up/magic-link/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify a step-up magic-link token; mint AAL1 step-up token", "operationId": "postAuthStepUpMagicLinkVerify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepUpMagicLinkVerifyRequest" } } } }, "responses": { "200": { "description": "Step-up token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "step_up_token": { "type": "string", "example": "abCdEf..." }, "token_type": { "type": "string", "enum": [ "StepUp" ] }, "expires_in": { "type": "number", "example": 300 } }, "required": [ "step_up_token", "token_type", "expires_in" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/step-up/email-otp/initiate": { "post": { "tags": [ "Auth" ], "summary": "Initiate a step-up email-OTP to the authenticated user email", "operationId": "postAuthStepUpEmailOtpInitiate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepUpEmailOtpInitiateRequest" } } } }, "responses": { "202": { "description": "Step-up OTP queued for delivery", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "sent" ] }, "email_masked": { "type": "string", "example": "b***@***.com" } }, "required": [ "status", "email_masked" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Email delivery temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/step-up/email-otp/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify a step-up email-OTP code; mint AAL1 step-up token", "operationId": "postAuthStepUpEmailOtpVerify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepUpEmailOtpVerifyRequest" } } } }, "responses": { "200": { "description": "Step-up token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "step_up_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "StepUp" ] }, "expires_in": { "type": "number" } }, "required": [ "step_up_token", "token_type", "expires_in" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid or expired OTP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/step-up/passkey/options": { "post": { "tags": [ "Auth" ], "summary": "Begin step-up passkey assertion ceremony", "operationId": "postAuthStepUpPasskeyOptions", "responses": { "200": { "description": "Assertion challenge issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge": { "type": "string" }, "rpId": { "type": "string" }, "allowCredentials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "public-key" ] }, "transports": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "type" ] } }, "userVerification": { "type": "string", "enum": [ "required", "preferred" ] }, "timeout": { "type": "number" } }, "required": [ "challenge", "rpId", "allowCredentials", "userVerification", "timeout" ] } } } }, "400": { "description": "No passkeys enrolled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Passkey relying-party ID misconfigured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/step-up/passkey/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify a step-up passkey assertion; mint AAL2 step-up token", "operationId": "postAuthStepUpPasskeyVerify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepUpPasskeyVerifyRequest" } } } }, "responses": { "200": { "description": "Step-up token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "step_up_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "StepUp" ] }, "expires_in": { "type": "number" } }, "required": [ "step_up_token", "token_type", "expires_in" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid assertion / AAL2 not satisfied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/passkeys/register-begin": { "post": { "tags": [ "Passkeys" ], "summary": "Begin passkey registration ceremony", "operationId": "postPasskeysRegisterBegin", "responses": { "200": { "description": "PublicKeyCredentialCreationOptionsJSON for WebAuthn credential creation", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Auth or step-up missing/expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Feature disabled or user not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/passkeys/register-finish": { "post": { "tags": [ "Passkeys" ], "summary": "Finish passkey registration ceremony", "operationId": "postPasskeysRegisterFinish", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyRegisterFinishRequest" } } } }, "responses": { "200": { "description": "Passkey registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "passkey_id": { "type": "string" } }, "required": [ "passkey_id" ] } } } }, "400": { "description": "Invalid registration response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Auth/step-up missing, challenge used, or RP-ID mismatch", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Feature disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Credential already registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/passkeys/assert-begin": { "post": { "tags": [ "Passkeys" ], "summary": "Begin passkey authentication ceremony", "operationId": "postPasskeysAssertBegin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyAssertBeginRequest" } } } }, "responses": { "200": { "description": "PublicKeyCredentialRequestOptionsJSON for WebAuthn signing", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Feature disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/passkeys/assert-finish": { "post": { "tags": [ "Passkeys" ], "summary": "Finish passkey authentication ceremony — returns tokens", "operationId": "postPasskeysAssertFinish", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyAssertFinishRequest" } } } }, "responses": { "200": { "description": "Authenticated — returns access + refresh tokens (aal=AAL2, amr=[\"webauthn\"])", "content": { "application/json": { "schema": { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "authenticated" ] }, "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "number" }, "token_type": { "type": "string", "enum": [ "Bearer" ] } }, "required": [ "next_step", "access_token", "refresh_token", "expires_in", "token_type" ] } } } }, "401": { "description": "Invalid signature/challenge or unknown credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Feature disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/{id}/passkeys": { "get": { "tags": [ "Passkeys" ], "summary": "List passkeys for a user", "operationId": "getUserPasskeys", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "List of passkeys", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nickname": { "type": "string" }, "aaguid": { "type": "string" }, "device_type": { "type": "string" }, "backed_up": { "type": "boolean" }, "backup_eligible": { "type": "boolean" }, "transports": { "type": "array", "items": { "type": "string" } }, "rp_id": { "type": "string" }, "last_used_at": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "device_type", "backed_up", "backup_eligible", "rp_id", "created_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Auth/step-up missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Cross-tenant or feature disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/{id}/passkeys/{pid}": { "patch": { "tags": [ "Passkeys" ], "summary": "Rename a passkey (nickname-only allow-list)", "operationId": "patchUserPasskey", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "pid", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyUpdateRequest" } } } }, "responses": { "200": { "description": "Renamed", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Auth/step-up missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Cross-tenant, not owned, or feature disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Passkeys" ], "summary": "Delete a passkey (blocks on last remaining sign-in method)", "operationId": "deleteUserPasskey", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "pid", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Auth/step-up missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Cross-tenant, not owned, or feature disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Cannot delete last sign-in method", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "tags": [ "System" ], "summary": "OAuth 2.0 Authorization Server Metadata (RFC 8414)", "operationId": "getOAuthMetadata", "responses": { "200": { "description": "Authorization server metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string", "description": "Authorization server issuer identifier (frozen at https://api.rakomi.com)", "example": "https://api.rakomi.com" }, "authorization_endpoint": { "type": "string", "description": "Browser-facing authorization endpoint", "example": "https://accounts.rakomi.com/authorize" }, "token_endpoint": { "type": "string", "description": "Token exchange endpoint", "example": "https://api.rakomi.com/oauth/token" }, "revocation_endpoint": { "type": "string", "description": "Token revocation endpoint", "example": "https://api.rakomi.com/oauth/revoke" }, "jwks_uri": { "type": "string", "description": "JSON Web Key Set URI", "example": "https://api.rakomi.com/.well-known/jwks.json" }, "response_types_supported": { "type": "array", "items": { "type": "string" }, "example": [ "code" ] }, "grant_types_supported": { "type": "array", "items": { "type": "string" }, "example": [ "authorization_code", "refresh_token" ] }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" }, "example": [ "client_secret_post" ] }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" }, "example": [ "S256" ] }, "scopes_supported": { "type": "array", "items": { "type": "string" }, "example": [ "openid", "email", "profile" ] }, "device_authorization_endpoint": { "type": "string", "description": "RFC 8628 device authorization endpoint", "example": "https://api.rakomi.com/oauth/device/code" }, "dpop_signing_alg_values_supported": { "type": "array", "items": { "type": "string" }, "description": "RFC 9449 §5.1 — DPoP-proof signing algorithms accepted by this AS", "example": [ "ES256", "EdDSA" ] }, "resource_indicators_supported": { "type": "boolean", "description": "RFC 8707 §3 — whether this AS honors the `resource` indicator on token requests", "example": true }, "backchannel_authentication_endpoint": { "type": "string", "description": "OIDC CIBA Core §7 backchannel authentication endpoint", "example": "https://api.rakomi.com/oauth/bc-authorize" }, "backchannel_token_delivery_modes_supported": { "type": "array", "items": { "type": "string" }, "description": "OIDC CIBA Core §4 — implemented delivery modes (poll-only; ping/push not implemented)", "example": [ "poll" ] }, "registration_endpoint": { "type": "string", "description": "RFC 7591 Dynamic Client Registration endpoint (software-statement-gated)", "example": "https://api.rakomi.com/oauth/register" }, "client_id_metadata_document_supported": { "type": "boolean", "description": "OAuth Client ID Metadata Document support (MCP Authorization) — present (true) only when CIMD is enabled in this environment", "example": true } }, "required": [ "issuer", "authorization_endpoint", "token_endpoint", "revocation_endpoint", "jwks_uri", "response_types_supported", "grant_types_supported", "token_endpoint_auth_methods_supported", "code_challenge_methods_supported", "scopes_supported", "device_authorization_endpoint", "dpop_signing_alg_values_supported", "resource_indicators_supported", "backchannel_authentication_endpoint", "backchannel_token_delivery_modes_supported" ] } } } } } } }, "/.well-known/openid-configuration": { "get": { "tags": [ "System" ], "summary": "OpenID Connect Discovery Document (OIDC Core 1.0 §4)", "operationId": "getOidcConfiguration", "responses": { "200": { "description": "OpenID Connect provider metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "userinfo_endpoint": { "type": "string" }, "end_session_endpoint": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "jwks_uri": { "type": "string" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "subject_types_supported": { "type": "array", "items": { "type": "string" } }, "id_token_signing_alg_values_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "claims_supported": { "type": "array", "items": { "type": "string" } }, "acr_values_supported": { "type": "array", "items": { "type": "string" }, "description": "Authentication Context Class Reference values this AS can issue in the acr claim. Compare with an exact, case-sensitive string match — never a prefix/substring check." }, "claims_parameter_supported": { "type": "boolean" }, "request_parameter_supported": { "type": "boolean" }, "request_uri_parameter_supported": { "type": "boolean" }, "backchannel_logout_supported": { "type": "boolean" }, "frontchannel_logout_supported": { "type": "boolean" }, "device_authorization_endpoint": { "type": "string" }, "dpop_signing_alg_values_supported": { "type": "array", "items": { "type": "string" } }, "backchannel_authentication_endpoint": { "type": "string" }, "backchannel_token_delivery_modes_supported": { "type": "array", "items": { "type": "string" } }, "registration_endpoint": { "type": "string" }, "client_id_metadata_document_supported": { "type": "boolean" } }, "required": [ "issuer", "authorization_endpoint", "token_endpoint", "userinfo_endpoint", "end_session_endpoint", "revocation_endpoint", "jwks_uri", "response_types_supported", "grant_types_supported", "subject_types_supported", "id_token_signing_alg_values_supported", "token_endpoint_auth_methods_supported", "code_challenge_methods_supported", "scopes_supported", "claims_supported", "acr_values_supported", "claims_parameter_supported", "request_parameter_supported", "request_uri_parameter_supported", "backchannel_logout_supported", "frontchannel_logout_supported", "device_authorization_endpoint", "dpop_signing_alg_values_supported", "backchannel_authentication_endpoint", "backchannel_token_delivery_modes_supported" ] } } } } } } }, "/v1/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Register a new user account", "operationId": "postAuthRegister", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "200": { "description": "Registration initiated — check email for verification", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Registration initiated — check email for verification" }, "next_step": { "type": "string", "description": "Forward-looking, human-reachable next step — present only when the account is held pending parent/guardian approval (GDPR Art. 8)." } }, "required": [ "message" ] } } } }, "400": { "description": "Validation error or consent not given", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Sandbox registration blocked, or self-registration disabled for this tenant (code `tenant/self_registration_disabled`) — the tenant admin can still provision accounts via CSV import or SCIM, or the API key is missing the `auth:register` scope (code `auth/insufficient_scope`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Anonymous user already claimed, or supplied email collides with another account", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/anonymous": { "post": { "tags": [ "Auth" ], "summary": "Create a short-lived anonymous user and issue an access/refresh token pair", "operationId": "postAuthAnonymous", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymousSigninRequest" } } } }, "responses": { "201": { "description": "Anonymous user created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymousSigninResponse" } } } }, "400": { "description": "Invalid public_metadata (too large or contains blocked keys)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "402": { "description": "MAU cap reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Anonymous sign-ins disabled for this tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Authenticate a user and receive access/refresh tokens", "operationId": "postAuthLogin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Login successful — returns tokens (authenticated) or MFA challenge", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "authenticated" ] }, "access_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIs..." }, "refresh_token": { "type": "string", "example": "v1.abc123def456..." }, "expires_in": { "type": "number", "example": 900 }, "token_type": { "type": "string", "enum": [ "Bearer" ] } }, "required": [ "next_step", "access_token", "refresh_token", "expires_in", "token_type" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "mfa_verify" ] }, "mfa_challenge_token": { "type": "string" }, "expires_in": { "type": "number" }, "available_methods": { "type": "array", "items": { "type": "string", "enum": [ "totp", "webauthn", "recovery_code" ] } } }, "required": [ "next_step", "mfa_challenge_token", "expires_in", "available_methods" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "mfa_setup_required" ] }, "grace_deadline_at": { "type": "string", "example": "2026-04-01T00:00:00.000Z" }, "access_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIs..." }, "refresh_token": { "type": "string", "example": "v1.abc123def456..." }, "expires_in": { "type": "number", "example": 900 }, "token_type": { "type": "string", "enum": [ "Bearer" ] } }, "required": [ "next_step", "grace_deadline_at", "access_token", "refresh_token", "expires_in", "token_type" ] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid credentials or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Email not verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/mfa/verify-login": { "post": { "tags": [ "Auth" ], "summary": "Complete MFA login challenge with TOTP code or recovery code", "operationId": "postAuthMfaVerifyLogin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaVerifyLoginRequest" } } } }, "responses": { "200": { "description": "MFA verified — returns tokens or OAuth authorization code (PKCE flow)", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "authenticated" ] }, "access_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIs..." }, "refresh_token": { "type": "string", "example": "v1.abc123def456..." }, "expires_in": { "type": "number", "example": 900 }, "token_type": { "type": "string", "enum": [ "Bearer" ] } }, "required": [ "next_step", "access_token", "refresh_token", "expires_in", "token_type" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "oauth_code" ] }, "authorization_code": { "type": "string", "example": "rak_code_abc123..." }, "redirect_uri": { "type": "string", "example": "https://app.example.com/callback" }, "state": { "type": "string", "example": "random_state_value" } }, "required": [ "next_step", "authorization_code", "redirect_uri" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "oauth_resume" ] }, "resume_url": { "type": "string", "example": "https://accounts.rakomi.com/api/auth/resume?ticket=…" } }, "required": [ "next_step", "resume_url" ] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid MFA code or expired/invalid challenge", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Account is blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/mfa/setup": { "post": { "tags": [ "Auth" ], "summary": "Initiate TOTP MFA setup — returns QR code and recovery codes", "operationId": "postAuthMfaSetup", "responses": { "200": { "description": "MFA setup initiated — display QR code and recovery codes to user", "headers": { "Cache-Control": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" }, "otpauth_uri": { "type": "string" }, "recovery_codes": { "type": "array", "items": { "type": "string" } } }, "required": [ "secret", "otpauth_uri", "recovery_codes" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "MFA already enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "MFA not configured on this instance", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/mfa/verify-setup": { "post": { "tags": [ "Auth" ], "summary": "Verify TOTP code and activate MFA", "operationId": "postAuthMfaVerifySetup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaVerifySetupRequest" } } } }, "responses": { "200": { "description": "MFA enabled — all existing sessions invalidated", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "enum": [ true ] } }, "required": [ "enabled" ] } } } }, "400": { "description": "Invalid TOTP code or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "MFA setup expired — restart setup", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/mfa": { "delete": { "tags": [ "Auth" ], "summary": "Disable TOTP MFA (requires current TOTP code + password)", "operationId": "deleteAuthMfa", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaDisableRequest" } } } }, "responses": { "204": { "description": "MFA disabled" }, "401": { "description": "Invalid TOTP code or password", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Account is blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "MFA not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/mfa/status": { "get": { "tags": [ "Auth" ], "summary": "Get MFA status for the authenticated user", "operationId": "getAuthMfaStatus", "responses": { "200": { "description": "MFA status", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "enabled_at": { "type": "string" }, "method": { "type": "string" } }, "required": [ "enabled" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/mfa/recovery-codes": { "post": { "tags": [ "Auth" ], "summary": "Regenerate MFA recovery codes (invalidates all existing codes)", "operationId": "postAuthMfaRecoveryCodes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaRegenerateCodesRequest" } } } }, "responses": { "200": { "description": "New recovery codes generated — display once and save securely", "content": { "application/json": { "schema": { "type": "object", "properties": { "recovery_codes": { "type": "array", "items": { "type": "string" } } }, "required": [ "recovery_codes" ] } } } }, "401": { "description": "Invalid TOTP code or password", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "MFA not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Refresh access token using a valid refresh token", "operationId": "postAuthRefresh", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } } }, "responses": { "200": { "description": "Token refreshed — returns new access and refresh tokens", "content": { "application/json": { "schema": { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "authenticated" ], "example": "authenticated" }, "access_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIs..." }, "refresh_token": { "type": "string", "example": "v1.abc123def456..." }, "expires_in": { "type": "number", "example": 900 }, "token_type": { "type": "string", "enum": [ "Bearer", "DPoP" ] } }, "required": [ "next_step", "access_token", "refresh_token", "expires_in", "token_type" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid, expired, or reused refresh token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Logout the current user session", "operationId": "postAuthLogout", "responses": { "204": { "description": "Logout successful — session invalidated" }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/me": { "get": { "tags": [ "Auth" ], "summary": "Get current user profile and active sessions", "operationId": "getAuthMe", "responses": { "200": { "description": "User profile with active sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "01912345-abcd-7def-8901-234567890abc" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "email_verified": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-07T12:00:00.000Z" }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "01912345-abcd-7def-8901-234567890abc" }, "ip_hash": { "type": "string", "example": "a1b2c3d4e5f6..." }, "user_agent_hash": { "type": "string", "example": "f6e5d4c3b2a1..." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-07T12:00:00.000Z" }, "last_used_at": { "type": "string", "format": "date-time", "example": "2026-03-07T12:00:00.000Z" }, "is_current": { "type": "boolean" } }, "required": [ "id", "ip_hash", "user_agent_hash", "created_at", "last_used_at", "is_current" ] } } }, "required": [ "id", "email", "email_verified", "created_at", "sessions" ] } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/me/sessions/{id}": { "delete": { "tags": [ "Auth" ], "summary": "Revoke a specific session", "operationId": "deleteAuthMeSession", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Session ID to revoke", "example": "019508a0-1234-7890-abcd-ef1234567890" }, "required": true, "description": "Session ID to revoke", "name": "id", "in": "path" } ], "responses": { "204": { "description": "Session revoked successfully" }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/verify-email": { "post": { "tags": [ "Auth" ], "summary": "Verify user email address with token", "operationId": "postAuthVerifyEmail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailRequest" } } } }, "responses": { "200": { "description": "Email verified successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Email verified successfully" } }, "required": [ "message" ] } } } }, "400": { "description": "Token expired, already used, or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/resend-verification": { "post": { "tags": [ "Auth" ], "summary": "Resend email verification", "operationId": "postAuthResendVerification", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendVerificationRequest" } } } }, "responses": { "200": { "description": "If email is registered, a verification email has been sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "If an account exists, a verification email has been sent" } }, "required": [ "message" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/forgot-password": { "post": { "tags": [ "Auth" ], "summary": "Request password reset email", "operationId": "postAuthForgotPassword", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordRequest" } } } }, "responses": { "200": { "description": "If email is registered, a password reset link has been sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "If an account exists, a password reset link has been sent" } }, "required": [ "message" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/reset-password": { "post": { "tags": [ "Auth" ], "summary": "Reset password with token", "operationId": "postAuthResetPassword", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } } }, "responses": { "200": { "description": "Password has been reset successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Password has been reset successfully" } }, "required": [ "message" ] } } } }, "400": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/change-password": { "post": { "tags": [ "Auth" ], "summary": "Change password (authenticated user)", "operationId": "postAuthChangePassword", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } } }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Password changed successfully" } }, "required": [ "message" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid credentials or missing authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/magic-link": { "post": { "tags": [ "Auth" ], "summary": "Request a magic link for end-user authentication", "operationId": "postAuthUserMagicLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserMagicLinkRequest" } } } }, "responses": { "200": { "description": "Magic link sent (or silently ignored for non-existent/blocked email)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "If your email is registered, a magic link has been sent" }, "resend_after_seconds": { "type": "number", "example": 60 } }, "required": [ "message", "resend_after_seconds" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Magic link feature disabled for this tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/magic-link/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify a magic link token and authenticate the user", "operationId": "postAuthUserMagicLinkVerify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserMagicLinkVerifyRequest" } } } }, "responses": { "200": { "description": "Token verified — authenticated, MFA challenge, setup required, link resent, or OAuth code", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "authenticated" ] }, "access_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIs..." }, "refresh_token": { "type": "string", "example": "v1.abc123def456..." }, "expires_in": { "type": "number", "example": 900 }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "is_new_user": { "type": "boolean", "enum": [ false ] } }, "required": [ "next_step", "access_token", "refresh_token", "expires_in", "token_type", "is_new_user" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "mfa_verify" ] }, "mfa_challenge_token": { "type": "string" }, "expires_in": { "type": "number" }, "available_methods": { "type": "array", "items": { "type": "string", "enum": [ "totp", "webauthn", "recovery_code" ] } } }, "required": [ "next_step", "mfa_challenge_token", "expires_in", "available_methods" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "mfa_setup_required" ] }, "grace_deadline_at": { "type": "string", "example": "2026-04-01T00:00:00.000Z" }, "access_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIs..." }, "refresh_token": { "type": "string", "example": "v1.abc123def456..." }, "expires_in": { "type": "number", "example": 900 }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "is_new_user": { "type": "boolean", "enum": [ false ] } }, "required": [ "next_step", "grace_deadline_at", "access_token", "refresh_token", "expires_in", "token_type", "is_new_user" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "link_resent" ] }, "message": { "type": "string", "example": "A new magic link has been sent" } }, "required": [ "next_step", "message" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "oauth_code" ] }, "authorization_code": { "type": "string", "example": "rak_code_abc123..." }, "redirect_uri": { "type": "string", "example": "https://app.example.com/callback" }, "state": { "type": "string", "example": "random_state_value" } }, "required": [ "next_step", "authorization_code", "redirect_uri" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "oauth_resume" ] }, "resume_url": { "type": "string", "example": "https://accounts.rakomi.com/api/auth/resume?ticket=…" } }, "required": [ "next_step", "resume_url" ] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid, expired, or already-used magic link; blocked user; MFA enforcement blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Feature disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/parental-consent/request": { "post": { "tags": [ "Auth" ], "summary": "Request (or re-request) a parental-consent email for a pending minor", "operationId": "postAuthParentalConsentRequest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParentalConsentRequest" } } } }, "responses": { "200": { "description": "Generic non-revealing acknowledgement (sent, or silently ignored)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/parental-consent/context": { "get": { "tags": [ "Auth" ], "summary": "Fetch the guardian consent landing context (non-mutating)", "operationId": "getAuthParentalConsentContext", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": true, "name": "token", "in": "query" } ], "responses": { "200": { "description": "Landing context (valid → disclosure, invalid → generic)", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "enum": [ "valid" ] }, "tenant_name": { "type": "string" }, "action": { "type": "string", "enum": [ "accept", "decline" ] }, "csrf": { "type": "string" } }, "required": [ "state", "tenant_name", "action", "csrf" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "invalid" ] } }, "required": [ "state" ] } ] } } } } } } }, "/v1/auth/parental-consent/consume": { "post": { "tags": [ "Auth" ], "summary": "Confirm a guardian ACCEPT/DECLINE (single-use, single-purpose)", "operationId": "postAuthParentalConsentConsume", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardianConsentConsume" } } } }, "responses": { "200": { "description": "Consume outcome (accepted / declined / invalid — non-enumerable)", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "accepted", "declined", "invalid" ] } }, "required": [ "result" ] } } } }, "403": { "description": "CSRF / origin rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/guardian/portal/context": { "get": { "tags": [ "Guardian" ], "summary": "Fetch the guardian management portal context (non-mutating, non-consuming)", "operationId": "getGuardianPortalContext", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": true, "name": "token", "in": "query" } ], "responses": { "200": { "description": "Portal context (valid → disclosure, invalid → single opaque body)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardianPortalContext" } } } } } } }, "/v1/guardian/portal/action": { "post": { "tags": [ "Guardian" ], "summary": "Perform a guardian management action (withdraw / export / delete)", "operationId": "postGuardianPortalAction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardianManagementMutate" } } } }, "responses": { "200": { "description": "Generic non-revealing acknowledgement (ok / invalid — non-enumerable)", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "ok", "invalid" ] } }, "required": [ "result" ], "additionalProperties": false } } } } } } }, "/v1/guardian/portal/request-link": { "post": { "tags": [ "Guardian" ], "summary": "Re-request a fresh guardian management link (single-use, rate-limited)", "operationId": "postGuardianPortalRequestLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardianManagementLinkRequest" } } } }, "responses": { "200": { "description": "Generic non-revealing acknowledgement (sent, or silently ignored)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/email-otp": { "post": { "tags": [ "Auth" ], "summary": "Request an email OTP for end-user authentication", "operationId": "postAuthUserEmailOtp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserEmailOtpRequest" } } } }, "responses": { "200": { "description": "OTP sent (or silently ignored for non-existent/blocked email)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "If your email is registered, a one-time code has been sent" }, "resend_after_seconds": { "type": "number", "example": 60 }, "expires_at": { "type": "string", "example": "2026-03-22T10:05:00.000Z" } }, "required": [ "message", "resend_after_seconds", "expires_at" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Email OTP feature disabled for this tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/email-otp/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify an email OTP code and authenticate the user", "operationId": "postAuthUserEmailOtpVerify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserEmailOtpVerifyRequest" } } } }, "responses": { "200": { "description": "Code verified — authenticated, MFA challenge, setup required, or OAuth code", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "authenticated" ] }, "access_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIs..." }, "refresh_token": { "type": "string", "example": "v1.abc123def456..." }, "expires_in": { "type": "number", "example": 900 }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "is_new_user": { "type": "boolean", "enum": [ false ] } }, "required": [ "next_step", "access_token", "refresh_token", "expires_in", "token_type", "is_new_user" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "mfa_verify" ] }, "mfa_challenge_token": { "type": "string" }, "expires_in": { "type": "number" }, "available_methods": { "type": "array", "items": { "type": "string", "enum": [ "totp", "webauthn", "recovery_code" ] } } }, "required": [ "next_step", "mfa_challenge_token", "expires_in", "available_methods" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "mfa_setup_required" ] }, "grace_deadline_at": { "type": "string", "example": "2026-04-01T00:00:00.000Z" }, "access_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIs..." }, "refresh_token": { "type": "string", "example": "v1.abc123def456..." }, "expires_in": { "type": "number", "example": 900 }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "is_new_user": { "type": "boolean", "enum": [ false ] } }, "required": [ "next_step", "grace_deadline_at", "access_token", "refresh_token", "expires_in", "token_type", "is_new_user" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "oauth_code" ] }, "authorization_code": { "type": "string", "example": "rak_code_abc123..." }, "redirect_uri": { "type": "string", "example": "https://app.example.com/callback" }, "state": { "type": "string", "example": "random_state_value" } }, "required": [ "next_step", "authorization_code", "redirect_uri" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "oauth_resume" ] }, "resume_url": { "type": "string", "example": "https://accounts.rakomi.com/api/auth/resume?ticket=…" } }, "required": [ "next_step", "resume_url" ] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid or expired OTP code; blocked user; MFA enforcement blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Feature disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/sms-otp": { "post": { "tags": [ "Auth" ], "summary": "Request an SMS OTP for end-user authentication", "operationId": "postAuthUserSmsOtp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSmsOtpRequest" } } } }, "responses": { "200": { "description": "OTP sent (or silently ignored for non-existent/unverified phone / disabled tenant)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "If the phone number exists, a verification code has been sent" }, "resend_after_seconds": { "type": "number", "example": 60 }, "expires_at": { "type": "string", "example": "2026-04-24T14:35:00.000Z" } }, "required": [ "message", "resend_after_seconds", "expires_at" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "501": { "description": "Mode not implemented", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "SMS OTP not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/sms-otp/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify an SMS OTP code and authenticate the user", "operationId": "postAuthUserSmsOtpVerify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSmsOtpVerifyRequest" } } } }, "responses": { "200": { "description": "Authenticated / MFA challenge / setup required / OAuth code", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "authenticated" ] }, "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "number" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "is_new_user": { "type": "boolean", "enum": [ false ] }, "profile_completion_hint": { "type": "string", "enum": [ "verify_email" ] } }, "required": [ "next_step", "access_token", "refresh_token", "expires_in", "token_type", "is_new_user" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "mfa_verify" ] }, "mfa_challenge_token": { "type": "string" }, "expires_in": { "type": "number" }, "available_methods": { "type": "array", "items": { "type": "string", "enum": [ "totp", "webauthn", "recovery_code" ] } } }, "required": [ "next_step", "mfa_challenge_token", "expires_in", "available_methods" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "mfa_setup_required" ] }, "grace_deadline_at": { "type": "string" }, "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "number" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "is_new_user": { "type": "boolean", "enum": [ false ] } }, "required": [ "next_step", "grace_deadline_at", "access_token", "refresh_token", "expires_in", "token_type", "is_new_user" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "oauth_code" ] }, "authorization_code": { "type": "string" }, "redirect_uri": { "type": "string" }, "state": { "type": "string" } }, "required": [ "next_step", "authorization_code", "redirect_uri" ] }, { "type": "object", "properties": { "next_step": { "type": "string", "enum": [ "oauth_resume" ] }, "resume_url": { "type": "string", "example": "https://accounts.rakomi.com/api/auth/resume?ticket=…" } }, "required": [ "next_step", "resume_url" ] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid/expired code, blocked user, or MFA blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Feature disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/phone/verify/request": { "post": { "tags": [ "Users" ], "summary": "Request a phone number verification code", "operationId": "postUsersMePhoneVerifyRequest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerifyRequest" } } } }, "responses": { "200": { "description": "Verification code dispatched", "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_at": { "type": "string", "example": "2026-04-24T14:45:00.000Z" }, "resend_after_seconds": { "type": "number", "example": 60 } }, "required": [ "expires_at", "resend_after_seconds" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid JWT", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Account in post-link cooldown", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "SMS OTP not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/phone/verify/confirm": { "post": { "tags": [ "Users" ], "summary": "Confirm a phone verification code and mark phone as verified", "operationId": "postUsersMePhoneVerifyConfirm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerifyConfirmRequest" } } } }, "responses": { "200": { "description": "Phone verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_verified_at": { "type": "string", "example": "2026-04-24T14:45:11.123Z" } }, "required": [ "phone_verified_at" ] } } } }, "400": { "description": "Code invalid/expired or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid JWT", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Phone already verified on another account OR post-link cooldown", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "SMS OTP not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/config": { "get": { "tags": [ "Auth" ], "summary": "Get tenant auth configuration", "description": "Returns enabled auth methods, social providers, and MFA policy for the tenant associated with the API key. Designed for SDK components to auto-discover available auth methods.", "operationId": "getAuthConfig", "responses": { "200": { "description": "Auth configuration", "headers": { "Cache-Control": { "schema": { "type": "string", "example": "private, max-age=300" }, "required": true } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "methods": { "type": "array", "items": { "type": "string" }, "example": [ "password", "magic_link", "email_otp" ] }, "social_providers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "sign_in": { "type": "boolean" }, "sign_up": { "type": "boolean" } }, "required": [ "sign_in", "sign_up" ] }, "example": { "google": { "sign_in": true, "sign_up": true }, "github": { "sign_in": true, "sign_up": false } }, "description": "Social providers enabled for sign-in, keyed by provider name. A provider absent from this object is not enabled for sign-in at all. `sign_up` is coupled to `sign_in` — a provider can never allow sign-up while its own sign-in is closed. This does NOT reflect the tenant-wide `self_registration_enabled` ceiling, which gates the password/email registration endpoint only. This field never carries end-user personal data — only tenant-level provider configuration." }, "mfa_enforced": { "type": "boolean", "example": false }, "mfa_grace_period_hours": { "type": "number", "example": 168 }, "branding": { "type": "object", "properties": { "logo_url": { "type": "string", "example": "https://api.rakomi.eu/v1/auth/branding/logo/01912345-abcd-7def-8901-234567890abc" }, "primary_color": { "type": "string", "example": "#4f46e5" }, "background_color": { "type": "string", "example": "#ffffff" }, "button_color": { "type": "string", "example": "#4f46e5" }, "text_color": { "type": "string", "example": "#111827" }, "button_text_color": { "type": "string", "example": "#ffffff", "description": "Text ON the button fill, for the light theme. Stored when the tenant overrides it; otherwise computed from the fill’s luminance." }, "heading_color": { "type": "string", "example": "#0b1220" }, "border_radius": { "type": "string", "example": "0.5rem" }, "tenant_name": { "type": "string", "example": "Acme Corp" }, "theme_mode": { "type": "string", "enum": [ "light", "dark", "both" ], "example": "both", "description": "Which palettes this tenant supports. These are CSS `color-scheme` semantics, not `prefers-color-scheme`: the value declares which palettes exist, and the end user's OS preference then selects one. `light` and `dark` additionally mean FORCE that scheme and ignore the preference; `both` means follow the preference. Emitted even when `light`, so a client can distinguish \"the tenant chose light-only\" from \"the tenant has no branding\" (in the latter case the whole `branding` object is absent). The six flat fields above always carry the LIGHT values. A client that meets an unrecognised value MUST fall back to `light` rather than reject the response — this set may gain members, and an installed client must keep working." }, "dark": { "type": "object", "properties": { "logo_url": { "type": "string", "example": "https://api.rakomi.eu/v1/auth/branding/logo/01912345-abcd-7def-8901-234567890abc?theme=dark" }, "primary_color": { "type": "string", "example": "#8ab4f8" }, "background_color": { "type": "string", "example": "#111827" }, "button_color": { "type": "string", "example": "#7599d3", "description": "The brand colour AS A FILL. Deliberately distinct from `primary_color`, which is the brand colour ON the background (links, accents) — the same colour can be readable as a fill and unreadable as link text." }, "button_text_color": { "type": "string", "example": "#111827", "description": "Text ON the button fill. The tenant may set it; when they have not, this is a SUGGESTION computed from the fill’s luminance (dark text on a light fill, light text on a dark one) so the label is never unreadable." }, "text_color": { "type": "string", "example": "#f9fafb" }, "heading_color": { "type": "string", "example": "#ffffff" } }, "description": "The dark-theme palette. Present when `theme_mode` is `dark` or `both` AND at least one dark value resolves — an empty palette is never emitted, so its presence always means there is something to paint. For `both` it travels alongside the flat light palette in this one response, so an end user flipping their OS theme mid-session never needs to refetch it (the response is cached). `border_radius` and `tenant_name` are theme-independent and are not repeated here. When the tenant uploaded only one logo, both `logo_url` values are the identical string — one image, one cache entry. A field the tenant left unset for dark may carry the light value instead, but only where that value is measurably readable against the dark background; where it is not, the field is omitted and the client's own default applies." } }, "required": [ "tenant_name" ] }, "self_registration_enabled": { "type": "boolean", "example": true, "description": "Whether password/email self-registration is open for this tenant. SCOPE — this switch gates the password/email registration endpoint AND the anonymous-session claim path (both the password-claim and social-claim variants), unconditionally, along with EUDI wallet sign-in — none of these three requires setting all of them; see the Registration control reference for what remains independent. It does not close social sign-up (each TIER-1 provider — google/github/microsoft/apple — carries its own `*_oauth_allow_signup` switch, unaffected by this switch; extended/tier-2 social providers have no equivalent switch yet). Enterprise SSO just-in-time provisioning honors this switch only as a FALLBACK — an explicit per-connection provisioning setting always wins, even when this switch is closed. Not to be confused with the OAuth Dynamic Client Registration `registration_endpoint` metadata field — this governs end-user account registration, not OAuth client registration." } }, "required": [ "methods", "social_providers", "mfa_enforced", "self_registration_enabled" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Tenant suspended", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "423": { "description": "Tenant deletion pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/branding/logo/{tenantId}": { "get": { "tags": [ "Auth" ], "summary": "Get tenant logo image", "description": "Returns the raw logo image for a tenant. Public endpoint — logos are displayed in tags which cannot send auth headers. Tenant UUID is unguessable. The optional `theme` query parameter selects the light or dark logo; when the tenant uploaded only one, that one is served for BOTH themes with a 200, so the response status never reveals which themes a tenant has configured.", "operationId": "getBrandingLogo", "parameters": [ { "schema": { "type": "string", "description": "Tenant ID (UUID)", "example": "01912345-abcd-7def-8901-234567890abc" }, "required": true, "description": "Tenant ID (UUID)", "name": "tenantId", "in": "path" }, { "schema": { "type": "string", "enum": [ "light", "dark" ], "description": "Which theme’s logo to serve. Omitted = light (the pre-existing behaviour, so the bare URL keeps working). A value outside the set is a 400, never a silent fallback — silently accepting it would make ?theme=1, ?theme=2 … unbounded distinct cache entries at one DB read each on the only unauthenticated route here.", "example": "dark" }, "required": false, "description": "Which theme’s logo to serve. Omitted = light (the pre-existing behaviour, so the bare URL keeps working). A value outside the set is a 400, never a silent fallback — silently accepting it would make ?theme=1, ?theme=2 … unbounded distinct cache entries at one DB read each on the only unauthenticated route here.", "name": "theme", "in": "query" } ], "responses": { "200": { "description": "Logo image", "headers": { "Content-Type": { "schema": { "type": "string", "example": "image/png" }, "required": true }, "Cache-Control": { "schema": { "type": "string", "example": "private, max-age=86400" }, "required": true }, "ETag": { "schema": { "type": "string", "example": "\"abc123\"" }, "required": true }, "Content-Disposition": { "schema": { "type": "string", "example": "inline" }, "required": true } } }, "304": { "description": "Not modified" }, "400": { "description": "Invalid tenant ID" }, "404": { "description": "Logo not found" }, "429": { "description": "Rate limited" } } } }, "/v1/auth/tenants/{slug}/oauth-status": { "get": { "tags": [ "Dashboard Auth" ], "summary": "Get OAuth provider status for a tenant by slug", "operationId": "getAuthTenantOAuthStatus", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Tenant slug", "example": "acme-corp" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "responses": { "200": { "description": "OAuth provider status", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_name": { "type": "string", "example": "Acme Corp" }, "providers": { "type": "object", "properties": { "google": { "type": "boolean", "example": true }, "github": { "type": "boolean", "example": false }, "microsoft": { "type": "boolean", "example": false }, "apple": { "type": "boolean", "example": false }, "discord": { "type": "boolean", "example": false }, "facebook": { "type": "boolean", "example": false }, "slack": { "type": "boolean", "example": false }, "twitter": { "type": "boolean", "example": false }, "gitlab": { "type": "boolean", "example": false }, "linkedin": { "type": "boolean", "example": false } }, "required": [ "google", "github", "microsoft", "apple", "discord", "facebook", "slack", "twitter", "gitlab", "linkedin" ] }, "eudi_enabled": { "type": "boolean", "example": false } }, "required": [ "tenant_name", "providers", "eudi_enabled" ] } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/eudi/initiate": { "post": { "tags": [ "Auth" ], "summary": "Initiate an EU Digital Identity Wallet login (OpenID4VP Verifier)", "operationId": "postAuthEudiInitiate", "responses": { "201": { "description": "Presentation request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EudiInitiateResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "EUDI login not enabled for this tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "EUDI not configured (no requested attributes)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "EUDI verifier key / trust anchors not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/eudi/response": { "post": { "tags": [ "Auth" ], "summary": "Wallet response endpoint (direct_post.jwt) — public, resolved by state", "operationId": "postAuthEudiResponse", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "state": { "type": "string", "minLength": 1 }, "response": { "type": "string", "minLength": 1, "description": "The compact JWE response." } }, "required": [ "state", "response" ] } } } }, "responses": { "200": { "description": "Response accepted (verification completed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] } } } }, "400": { "description": "Malformed response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Verification failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Response too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Session requires a disclosed email", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/eudi/result/{state}": { "get": { "tags": [ "Auth" ], "summary": "Poll an EUDI login result (cross-device) and collect the one-time token handoff", "operationId": "getAuthEudiResult", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "state", "in": "path" } ], "responses": { "200": { "description": "Login status (+ tokens once verified)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EudiResultResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/eudi/age-verification/initiate": { "post": { "tags": [ "Auth" ], "summary": "Initiate a privacy-preserving EU Digital Identity Wallet age verification (registration)", "operationId": "postAuthEudiAgeVerificationInitiate", "responses": { "201": { "description": "Age-verification presentation request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EudiAgeVerificationInitiateResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "EUDI age verification / minor protection not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Tenant threshold has no supported wallet predicate (use the DOB flow)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "EUDI verifier key / trust anchors not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/eudi/age-verification/response": { "post": { "tags": [ "Auth" ], "summary": "Wallet age-proof response endpoint (direct_post.jwt) — public, resolved by state", "operationId": "postAuthEudiAgeVerificationResponse", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "state": { "type": "string", "minLength": 1 }, "response": { "type": "string", "minLength": 1, "description": "The compact JWE response." } }, "required": [ "state", "response" ] } } } }, "responses": { "200": { "description": "Response accepted (the determination is available via the result poll)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] } } } }, "400": { "description": "Malformed response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Response too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/eudi/age-verification/result/{state}": { "get": { "tags": [ "Auth" ], "summary": "Poll an EUDI age-verification result and collect the opaque proceed token", "operationId": "getAuthEudiAgeVerificationResult", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "state", "in": "path" } ], "responses": { "200": { "description": "Age-verification status (+ opaque token once determined)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EudiAgeVerificationResultResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/invitation/accept": { "post": { "tags": [ "Dashboard Auth" ], "summary": "Accept a tenant invitation", "operationId": "acceptInvitation", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "Invitation token from email link" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Invitation accepted, session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_url": { "type": "string", "example": "https://example.com/callback" } }, "required": [ "redirect_url" ] } } } }, "400": { "description": "Invalid or already used token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "Invitation expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/oauth-scopes": { "get": { "tags": [ "OAuth Custom Scopes" ], "summary": "List the tenant's registered custom scopes", "operationId": "listOAuthCustomScopes", "responses": { "200": { "description": "Registered custom scopes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "01912345-abcd-7def-8901-234567890abc" }, "scope": { "type": "string", "example": "acme:invoices.read" }, "display_name": { "type": "string", "example": "Read your invoices" }, "description": { "type": "string", "example": "Lets Acme read invoices you have issued." }, "created_at": { "type": "string", "example": "2026-07-14T12:00:00.000Z" }, "updated_at": { "type": "string", "example": "2026-07-14T12:00:00.000Z" } }, "required": [ "id", "scope", "display_name", "created_at", "updated_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "OAuth Custom Scopes" ], "summary": "Register a custom scope", "operationId": "createOAuthCustomScope", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "maxLength": 128, "description": "Namespaced scope, exactly one colon (:)", "example": "acme:invoices.read" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Consent-screen label, shown verbatim to the user", "example": "Read your invoices" }, "description": { "type": "string", "maxLength": 1024, "description": "Consent-screen subtitle", "example": "Lets Acme read invoices you have issued." } }, "required": [ "scope", "display_name" ] } } } }, "responses": { "201": { "description": "Custom scope registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "01912345-abcd-7def-8901-234567890abc" }, "scope": { "type": "string", "example": "acme:invoices.read" }, "display_name": { "type": "string", "example": "Read your invoices" }, "description": { "type": "string", "example": "Lets Acme read invoices you have issued." }, "created_at": { "type": "string", "example": "2026-07-14T12:00:00.000Z" }, "updated_at": { "type": "string", "example": "2026-07-14T12:00:00.000Z" } }, "required": [ "id", "scope", "display_name", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid scope or copy", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Scope already registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/oauth-scopes/{id}": { "patch": { "tags": [ "OAuth Custom Scopes" ], "summary": "Update a custom scope's consent-screen copy", "description": "The `scope` string itself is immutable — renaming it would orphan every client registration and consent grant referencing the old value without revoking anything. Rename = delete + create.", "operationId": "updateOAuthCustomScope", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": [ "string", "null" ], "maxLength": 1024 } } } } } }, "responses": { "200": { "description": "Custom scope updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "01912345-abcd-7def-8901-234567890abc" }, "scope": { "type": "string", "example": "acme:invoices.read" }, "display_name": { "type": "string", "example": "Read your invoices" }, "description": { "type": "string", "example": "Lets Acme read invoices you have issued." }, "created_at": { "type": "string", "example": "2026-07-14T12:00:00.000Z" }, "updated_at": { "type": "string", "example": "2026-07-14T12:00:00.000Z" } }, "required": [ "id", "scope", "display_name", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid scope or copy", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Custom scope not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "OAuth Custom Scopes" ], "summary": "De-register a custom scope and REVOKE everything carrying it", "description": "Transactionally removes the scope from the registry, strips it from every client registration, narrows every consent grant, invalidates pending authorization codes, and revokes the sessions that carry it. Revocation is coarse by design: a user who granted this scope to an app is signed out of that app entirely, because sessions are not scope-selective.", "operationId": "deleteOAuthCustomScope", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Custom scope de-registered and all grants revoked" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Custom scope not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/resources/{resourceId}/scopes": { "get": { "tags": [ "Resource Scope Catalog" ], "summary": "List a resource's registered scope-catalog entries", "operationId": "listResourceScopeCatalogEntries", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "resourceId", "in": "path" } ], "responses": { "200": { "description": "Registered scope-catalog entries (empty array for an unowned/non-existent resource — AC#4 read is unrestricted, but only over resources this tenant can see)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "01912345-abcd-7def-8901-234567890abc" }, "resource_id": { "type": "string", "example": "01912345-abcd-7def-8901-234567890abd" }, "scope_name": { "type": "string", "example": "mcp:tools:custom" }, "status": { "type": "string", "example": "pending_review" }, "sensitivity": { "type": "string", "example": "elevated" }, "requires_platform_enable": { "type": "boolean" }, "display_metadata": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "i18n_key" ] }, "i18n_key": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "kind", "i18n_key" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "locale_text" ] }, "locale_text": { "type": "object", "properties": { "en": { "type": "string", "minLength": 1, "maxLength": 256 }, "pl": { "type": "string", "minLength": 1, "maxLength": 256 }, "de": { "type": "string", "minLength": 1, "maxLength": 256 }, "fr": { "type": "string", "minLength": 1, "maxLength": 256 }, "es": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "en", "pl", "de", "fr", "es" ], "additionalProperties": false } }, "required": [ "kind", "locale_text" ], "additionalProperties": false } ] }, "created_at": { "type": "string", "example": "2026-08-06T12:00:00.000Z" }, "updated_at": { "type": "string", "example": "2026-08-06T12:00:00.000Z" } }, "required": [ "id", "resource_id", "scope_name", "status", "sensitivity", "requires_platform_enable", "display_metadata", "created_at", "updated_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "Resource Scope Catalog" ], "summary": "Register a new scope on a resource this tenant owns", "description": "Every registration starts `status = pending_review` and passes through an asynchronous review queue before activation; a `pending_review` scope is not usable in a minted token until approved.", "operationId": "createResourceScopeCatalogEntry", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "resourceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scope_name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The scope string as it will appear in a minted token scope claim", "example": "mcp:tools:custom" }, "sensitivity": { "type": "string", "enum": [ "normal", "elevated" ], "description": "Self-declared risk level. Only `normal` scopes are listed on the end-user consent screen, and `elevated` ones are triaged more strictly during review. It does not by itself restrict which scopes a token may carry. Omitted defaults to `elevated`, the more restrictive value." }, "display_metadata": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "i18n_key" ] }, "i18n_key": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "kind", "i18n_key" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "locale_text" ] }, "locale_text": { "type": "object", "properties": { "en": { "type": "string", "minLength": 1, "maxLength": 256 }, "pl": { "type": "string", "minLength": 1, "maxLength": 256 }, "de": { "type": "string", "minLength": 1, "maxLength": 256 }, "fr": { "type": "string", "minLength": 1, "maxLength": 256 }, "es": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "en", "pl", "de", "fr", "es" ], "additionalProperties": false } }, "required": [ "kind", "locale_text" ], "additionalProperties": false } ] } }, "required": [ "scope_name", "display_metadata" ] } } } }, "responses": { "201": { "description": "Scope registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "01912345-abcd-7def-8901-234567890abc" }, "resource_id": { "type": "string", "example": "01912345-abcd-7def-8901-234567890abd" }, "scope_name": { "type": "string", "example": "mcp:tools:custom" }, "status": { "type": "string", "example": "pending_review" }, "sensitivity": { "type": "string", "example": "elevated" }, "requires_platform_enable": { "type": "boolean" }, "display_metadata": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "i18n_key" ] }, "i18n_key": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "kind", "i18n_key" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "locale_text" ] }, "locale_text": { "type": "object", "properties": { "en": { "type": "string", "minLength": 1, "maxLength": 256 }, "pl": { "type": "string", "minLength": 1, "maxLength": 256 }, "de": { "type": "string", "minLength": 1, "maxLength": 256 }, "fr": { "type": "string", "minLength": 1, "maxLength": 256 }, "es": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "en", "pl", "de", "fr", "es" ], "additionalProperties": false } }, "required": [ "kind", "locale_text" ], "additionalProperties": false } ] }, "created_at": { "type": "string", "example": "2026-08-06T12:00:00.000Z" }, "updated_at": { "type": "string", "example": "2026-08-06T12:00:00.000Z" } }, "required": [ "id", "resource_id", "scope_name", "status", "sensitivity", "requires_platform_enable", "display_metadata", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid scope name, or a cap/reserved-namespace rejection", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The platform resource catalog may not be modified via the self-service API", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Resource (or catalog entry) not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Scope already registered on this resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/resources/{resourceId}/scopes/{id}": { "delete": { "tags": [ "Resource Scope Catalog" ], "summary": "De-register a scope", "operationId": "deleteResourceScopeCatalogEntry", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "resourceId", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Scope de-registered" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The platform resource catalog may not be modified via the self-service API", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Resource (or catalog entry) not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/agents": { "get": { "tags": [ "Users" ], "summary": "List AI agents that have ever acted on my behalf", "operationId": "listMyAgents", "responses": { "200": { "description": "Agent list", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/agents/{agentClientId}": { "delete": { "tags": [ "Users" ], "summary": "Revoke an AI agent from acting on my behalf", "operationId": "revokeMyAgent", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "agentClientId", "in": "path" } ], "responses": { "200": { "description": "Agent revoked for this user (idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeMyAgentResponse" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/agents/{agentClientId}/restore": { "post": { "tags": [ "Users" ], "summary": "Restore a previously revoked AI agent to act on my behalf", "operationId": "restoreMyAgent", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "agentClientId", "in": "path" } ], "responses": { "200": { "description": "Agent restored for this user (idempotent). Restoring does not re-grant any capability — the last recorded consent decision still applies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreMyAgentResponse" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/authorize": { "get": { "tags": [ "OAuth" ], "summary": "OAuth 2.0 Authorization Endpoint", "operationId": "oauthAuthorize", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "response_type", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "client_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "scope", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "nonce", "in": "query" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "required": false, "name": "dpop_jkt", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "prompt", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "resource", "in": "query" } ], "responses": { "200": { "description": "Login required or consent required (API-first flow)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LoginRequiredResponse" }, { "$ref": "#/components/schemas/ConsentRequiredResponse" } ] } } } }, "302": { "description": "Redirect with authorization code (?code=&state=&iss=) or error (?error=&error_description=&state=&iss=)" }, "400": { "description": "Invalid client_id or redirect_uri — JSON error, MUST NOT redirect (RFC 6749 §4.1.2.1)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "temporarily_unavailable" ] }, "error_description": { "type": "string", "example": "Too many requests" } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "OAuth" ], "summary": "Submit OAuth 2.0 consent decision", "operationId": "oauthConsent", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "deny" ] }, "client_id": { "type": "string" }, "redirect_uri": { "type": "string" }, "state": { "type": "string", "maxLength": 512 }, "code_challenge": { "type": "string", "maxLength": 128 }, "code_challenge_method": { "type": "string" }, "response_type": { "type": "string" }, "scope": { "type": "string", "maxLength": 256 }, "nonce": { "type": "string", "maxLength": 256 }, "resource": { "type": "string" }, "resource_commitment": { "type": "string" }, "agent_scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "decision" ] } } } }, "responses": { "302": { "description": "Redirect with authorization code (?code=&state=&iss=) or error (?error=&error_description=&state=&iss=)" }, "400": { "description": "Invalid client_id or redirect_uri — JSON error, MUST NOT redirect (RFC 6749 §4.1.2.1)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_request" }, "error_description": { "type": "string", "example": "Unknown client_id" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_request" }, "error_description": { "type": "string", "example": "Valid Bearer token required" } }, "required": [ "error" ] } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_request" }, "error_description": { "type": "string", "example": "Request body too large" } }, "required": [ "error" ] } } } } } } }, "/oauth/token": { "post": { "tags": [ "OAuth" ], "summary": "Exchange authorization code, refresh token, or client credentials for access tokens (max body: 8192 bytes)", "operationId": "oauthToken", "responses": { "200": { "description": "Token response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIs..." }, "token_type": { "type": "string", "enum": [ "Bearer", "DPoP" ] }, "expires_in": { "type": "number", "example": 900 }, "refresh_token": { "type": "string", "example": "v1.abc123def456..." }, "scope": { "type": "string", "example": "read write" }, "id_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." }, "issued_token_type": { "type": "string", "example": "urn:ietf:params:oauth:token-type:access_token" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] } } } }, "400": { "description": "Invalid request or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_grant" }, "error_description": { "type": "string", "example": "Authorization code expired" }, "error_uri": { "type": "string", "example": "https://docs.rakomi.dev/errors/invalid-grant" } }, "required": [ "error" ] } } } }, "401": { "description": "Client authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_grant" }, "error_description": { "type": "string", "example": "Authorization code expired" }, "error_uri": { "type": "string", "example": "https://docs.rakomi.dev/errors/invalid-grant" } }, "required": [ "error" ] } } } }, "403": { "description": "Tier-gated grant (e.g., token-exchange on Free tier)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_grant" }, "error_description": { "type": "string", "example": "Authorization code expired" }, "error_uri": { "type": "string", "example": "https://docs.rakomi.dev/errors/invalid-grant" } }, "required": [ "error" ] } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_grant" }, "error_description": { "type": "string", "example": "Authorization code expired" }, "error_uri": { "type": "string", "example": "https://docs.rakomi.dev/errors/invalid-grant" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_grant" }, "error_description": { "type": "string", "example": "Authorization code expired" }, "error_uri": { "type": "string", "example": "https://docs.rakomi.dev/errors/invalid-grant" } }, "required": [ "error" ] } } } }, "503": { "description": "Authorization state temporarily unavailable — retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_grant" }, "error_description": { "type": "string", "example": "Authorization code expired" }, "error_uri": { "type": "string", "example": "https://docs.rakomi.dev/errors/invalid-grant" } }, "required": [ "error" ] } } } } } } }, "/oauth/revoke": { "post": { "tags": [ "OAuth" ], "summary": "Revoke an OAuth access or refresh token (max body: 8192 bytes)", "operationId": "oauthRevoke", "responses": { "200": { "description": "Token revoked (always 200 per RFC 7009)" }, "401": { "description": "Client authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_client" }, "error_description": { "type": "string", "example": "Client authentication failed" }, "error_uri": { "type": "string", "example": "https://docs.rakomi.dev/errors/invalid-client" } }, "required": [ "error", "error_description" ] } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_client" }, "error_description": { "type": "string", "example": "Client authentication failed" }, "error_uri": { "type": "string", "example": "https://docs.rakomi.dev/errors/invalid-client" } }, "required": [ "error", "error_description" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_client" }, "error_description": { "type": "string", "example": "Client authentication failed" }, "error_uri": { "type": "string", "example": "https://docs.rakomi.dev/errors/invalid-client" } }, "required": [ "error", "error_description" ] } } } } } } }, "/oauth/register": { "post": { "tags": [ "OAuth" ], "summary": "RFC 7591 Dynamic Client Registration (software-statement-gated, or anonymous per tenant opt-in)", "description": "Two registration modes share this endpoint.\n\n**1. Software statement (default).** The request carries a signed `software_statement` from a\ntrusted issuer. This is the only mode available unless a tenant has explicitly opted in to the\nsecond one.\n\n**2. Anonymous (RFC 7591 §3), per-tenant OPT-IN.** No `software_statement`, no requester\nauthentication. The request instead carries `rakomi_tenant_id` — a **routing hint**, not an\nauthorization: possessing it grants nothing, and the tenant's own opt-in is what authorizes the\nregistration. It is a private (non-IANA) client-metadata extension; RFC 7591 §3.1 requires an\nauthorization server to ignore metadata it does not understand, so sending it to a non-Rakomi AS\nis safe. `tenant_id` is accepted as a tolerated alias for one release; supplying both with\ndifferent values is rejected.\n\nAnonymous registration produces a PUBLIC client: PKCE-only, no `client_secret`, loopback\nredirect URIs (RFC 8252 §7.3), `authorization_code` only, user consent always required, subject\nto per-tenant quotas and auto-expiry. Every rejection on this path returns one uniform 400 —\ndeliberately, so the endpoint cannot be used to discover which tenants exist.", "operationId": "oauthRegister", "responses": { "201": { "description": "Client registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientRegistrationResponse" } } } }, "400": { "description": "Invalid registration", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited / quota exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "DCR temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/oauth/register/{client_id}": { "get": { "tags": [ "OAuth" ], "summary": "RFC 7592 Read the current client registration (reg-token Bearer auth; no /v1/ prefix)", "operationId": "oauthRegisterRead", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "client_id", "in": "path" } ], "responses": { "200": { "description": "Client information", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Invalid registration access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "DCR temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } } } }, "put": { "tags": [ "OAuth" ], "summary": "RFC 7592 Replace client metadata (re-clamped through the DCR policy ceiling)", "operationId": "oauthRegisterUpdate", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "client_id", "in": "path" } ], "responses": { "200": { "description": "Client updated", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid client metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid registration access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "DCR temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "OAuth" ], "summary": "RFC 7592 Deprovision the client (terminal — invalidates all issued tokens)", "operationId": "oauthRegisterDelete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "client_id", "in": "path" } ], "responses": { "204": { "description": "Client deprovisioned" }, "401": { "description": "Invalid registration access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "DCR temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/oauth/userinfo": { "get": { "tags": [ "OAuth" ], "summary": "OpenID Connect UserInfo Endpoint (OIDC Core 1.0 §5.3)", "operationId": "oidcUserinfo", "responses": { "200": { "description": "UserInfo claims for the authenticated user", "content": { "application/json": { "schema": { "type": "object", "properties": { "sub": { "type": "string", "example": "usr_01J..." }, "email": { "type": "string", "example": "user@example.com" }, "email_verified": { "type": "boolean" }, "updated_at": { "type": "number", "example": 1713350400, "description": "Unix timestamp of last profile update" }, "org_id": { "type": "string" }, "org_role": { "type": "string" }, "org_memberships": { "type": "array", "items": { "type": "object", "properties": { "org_id": { "type": "string" }, "org_slug": { "type": "string" }, "org_role": { "type": "string" }, "membership_public_metadata": { "type": "object", "additionalProperties": {} } }, "required": [ "org_id", "org_slug", "org_role" ] } } }, "required": [ "sub" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Token does not have openid scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "OAuth" ], "summary": "OpenID Connect UserInfo Endpoint — POST variant (OIDC Core 1.0 §5.3)", "operationId": "oidcUserinfoPost", "responses": { "200": { "description": "UserInfo claims for the authenticated user", "content": { "application/json": { "schema": { "type": "object", "properties": { "sub": { "type": "string", "example": "usr_01J..." }, "email": { "type": "string", "example": "user@example.com" }, "email_verified": { "type": "boolean" }, "updated_at": { "type": "number", "example": 1713350400, "description": "Unix timestamp of last profile update" }, "org_id": { "type": "string" }, "org_role": { "type": "string" }, "org_memberships": { "type": "array", "items": { "type": "object", "properties": { "org_id": { "type": "string" }, "org_slug": { "type": "string" }, "org_role": { "type": "string" }, "membership_public_metadata": { "type": "object", "additionalProperties": {} } }, "required": [ "org_id", "org_slug", "org_role" ] } } }, "required": [ "sub" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Token does not have openid scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/oauth/google/authorize": { "get": { "tags": [ "Google OAuth" ], "summary": "Initiate Google OAuth flow", "operationId": "getGoogleOAuthAuthorize", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tenant_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tenant_slug", "in": "query" }, { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string", "format": "email" }, "required": false, "name": "login_hint", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "oauth_state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_client_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "oauth_code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "oauth_scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_resource", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "oauth_resume_binding", "in": "query" } ], "responses": { "302": { "description": "Redirect to Google authorization endpoint" }, "400": { "description": "Invalid redirect_uri or missing tenant identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found or Google OAuth not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/callback/google": { "get": { "tags": [ "Google OAuth" ], "summary": "Google OAuth callback", "operationId": "getGoogleOAuthCallback", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error_description", "in": "query" } ], "responses": { "302": { "description": "Redirect with tokens or to consent page" }, "400": { "description": "Invalid state or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/google/consent": { "post": { "tags": [ "Google OAuth" ], "summary": "Accept consent and create user via Google OAuth", "operationId": "postGoogleOAuthConsent", "responses": { "302": { "description": "Redirect with tokens to consumer app" }, "400": { "description": "Invalid or expired state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/google/consent-state": { "get": { "tags": [ "Google OAuth" ], "summary": "Fetch consent preview data for Google OAuth consent interstitial", "operationId": "getGoogleConsentState", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Consent state token" }, "required": true, "description": "Consent state token", "name": "state", "in": "query" } ], "responses": { "200": { "description": "Consent preview data", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "example": "Anna Kowalska" }, "email": { "type": "string", "example": "anna@example.com" }, "tenant_name": { "type": "string", "example": "Fizjo Pro" }, "tenant_logo_url": { "type": [ "string", "null" ], "example": null }, "privacy_policy_url": { "type": [ "string", "null" ], "example": "https://fizjo-pro.pl/privacy" }, "expires_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" } }, "required": [ "name", "email", "tenant_name", "tenant_logo_url", "privacy_policy_url", "expires_at" ] } } } }, "400": { "description": "Invalid or expired state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/github/authorize": { "get": { "tags": [ "GitHub OAuth" ], "summary": "Initiate GitHub OAuth flow", "operationId": "getGitHubOAuthAuthorize", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tenant_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tenant_slug", "in": "query" }, { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "login_hint", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "oauth_state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_client_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "oauth_code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "oauth_scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_resource", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "oauth_resume_binding", "in": "query" } ], "responses": { "302": { "description": "Redirect to GitHub authorization endpoint" }, "400": { "description": "Invalid redirect_uri or missing tenant identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found or GitHub OAuth not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "State table DoS limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/oauth/device/authorize": { "post": { "tags": [ "OAuth Device Code" ], "summary": "Initiate RFC 8628 device authorization", "operationId": "postOAuthDeviceAuthorize", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "publishable_key": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "maxLength": 256 } }, "required": [ "publishable_key" ] } } } }, "responses": { "200": { "description": "Issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri": { "type": "string" }, "verification_uri_complete": { "type": "string" }, "expires_in": { "type": "number" }, "interval": { "type": "number" } }, "required": [ "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Publishable key unknown", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/oauth/device/token": { "post": { "tags": [ "OAuth Device Code" ], "summary": "Poll RFC 8628 device authorization grant", "operationId": "postOAuthDeviceToken", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string", "minLength": 1 }, "publishable_key": { "type": "string", "minLength": 1 }, "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:device_code" ] } }, "required": [ "device_code", "publishable_key", "grant_type" ] } } } }, "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "number" }, "token_type": { "type": "string", "enum": [ "Bearer" ] } }, "required": [ "access_token", "refresh_token", "expires_in", "token_type" ] } } } }, "400": { "description": "Polling response (RFC 8628 errors)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "authorization_pending", "slow_down", "access_denied", "expired_token", "invalid_grant" ] }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Cross-tenant or unknown device_code", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/oauth/device/approve": { "post": { "tags": [ "OAuth Device Code" ], "summary": "Approve an RFC 8628 device authorization (dashboard member)", "operationId": "postOAuthDeviceApprove", "description": "Dashboard member endpoint that approves a pending device-code grant identified by the human-friendly user_code. Atomic state transition pending → approved with end-user binding. Cross-tenant lookups collapse to 404 (NEVER 403) per CLAUDE.md belt-and-suspenders.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthDeviceApproveRequest" } } } }, "responses": { "200": { "description": "Device authorization approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthDeviceApproveResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient role on tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown user_code (or cross-tenant collapse)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Row already in non-pending state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "410": { "description": "Row expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/oauth/device/code": { "post": { "tags": [ "OAuth Device Code" ], "summary": "Initiate RFC 8628 device authorization (public OAuth-spec endpoint)", "operationId": "postOAuthDeviceCode", "responses": { "200": { "description": "Issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri": { "type": "string" }, "verification_uri_complete": { "type": "string" }, "expires_in": { "type": "number" }, "interval": { "type": "number" }, "message": { "type": "string" } }, "required": [ "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Client authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "Body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/oauth/bc-authorize": { "post": { "tags": [ "OAuth CIBA" ], "summary": "Initiate OIDC CIBA Core 1.0 backchannel authentication request", "operationId": "postOAuthBcAuthorize", "responses": { "200": { "description": "Issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_req_id": { "type": "string" }, "expires_in": { "type": "number" }, "interval": { "type": "number" } }, "required": [ "auth_req_id", "expires_in", "interval" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Client authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Tier-gated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "Body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/auth/oauth/device/deny": { "post": { "tags": [ "OAuth Device Code" ], "summary": "Deny an RFC 8628 device authorization (dashboard member)", "operationId": "postOAuthDeviceDeny", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthDeviceDenyRequest" } } } }, "responses": { "200": { "description": "Device authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthDeviceDenyResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient role on tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown user_code (or cross-tenant collapse)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Row already in non-pending state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "410": { "description": "Row expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "not_found", "expired_token", "already_approved", "already_denied", "access_denied" ] }, "error_description": { "type": "string" }, "error_uri": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/oauth/callback/github": { "get": { "tags": [ "GitHub OAuth" ], "summary": "GitHub OAuth callback", "operationId": "getGitHubOAuthCallback", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error_description", "in": "query" } ], "responses": { "302": { "description": "Redirect with tokens or to consent page" }, "400": { "description": "Invalid state or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/github/consent": { "post": { "tags": [ "GitHub OAuth" ], "summary": "Accept consent and create user via GitHub OAuth", "operationId": "postGitHubOAuthConsent", "responses": { "302": { "description": "Redirect with tokens to consumer app" }, "400": { "description": "Invalid or expired state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/github/consent-state": { "get": { "tags": [ "GitHub OAuth" ], "summary": "Fetch consent preview data for GitHub OAuth consent interstitial", "operationId": "getGitHubConsentState", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Consent state token" }, "required": true, "description": "Consent state token", "name": "state", "in": "query" } ], "responses": { "200": { "description": "Consent preview data", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "example": "Anna Kowalska" }, "email": { "type": "string", "example": "anna@example.com" }, "tenant_name": { "type": "string", "example": "Fizjo Pro" }, "tenant_logo_url": { "type": [ "string", "null" ], "example": null }, "privacy_policy_url": { "type": [ "string", "null" ], "example": "https://fizjo-pro.pl/privacy" }, "expires_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" } }, "required": [ "name", "email", "tenant_name", "tenant_logo_url", "privacy_policy_url", "expires_at" ] } } } }, "400": { "description": "Invalid or expired state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/microsoft/authorize": { "get": { "tags": [ "Microsoft OAuth" ], "summary": "Initiate Microsoft OAuth flow", "operationId": "getMicrosoftOAuthAuthorize", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tenant_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tenant_slug", "in": "query" }, { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string", "maxLength": 254 }, "required": false, "name": "login_hint", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "oauth_state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_client_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "oauth_code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "oauth_scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_resource", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "oauth_resume_binding", "in": "query" } ], "responses": { "302": { "description": "Redirect to Microsoft authorization endpoint" }, "400": { "description": "Invalid redirect_uri or missing tenant identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found or Microsoft OAuth not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "State table DoS limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/callback/microsoft": { "get": { "tags": [ "Microsoft OAuth" ], "summary": "Microsoft OAuth callback", "operationId": "getMicrosoftOAuthCallback", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "error", "in": "query" }, { "schema": { "type": "string", "maxLength": 2048 }, "required": false, "name": "error_description", "in": "query" } ], "responses": { "302": { "description": "Redirect with tokens or to consent page" }, "400": { "description": "Invalid state or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/microsoft/consent": { "post": { "tags": [ "Microsoft OAuth" ], "summary": "Accept consent and create user via Microsoft OAuth", "operationId": "postMicrosoftOAuthConsent", "responses": { "302": { "description": "Redirect with tokens to consumer app" }, "400": { "description": "Invalid or expired state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/microsoft/consent-state": { "get": { "tags": [ "Microsoft OAuth" ], "summary": "Fetch consent preview data for Microsoft OAuth consent interstitial", "operationId": "getMicrosoftConsentState", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Consent state token" }, "required": true, "description": "Consent state token", "name": "state", "in": "query" } ], "responses": { "200": { "description": "Consent preview data", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "example": "Anna Kowalska" }, "email": { "type": "string", "example": "anna@example.com" }, "tenant_name": { "type": "string", "example": "Fizjo Pro" }, "tenant_logo_url": { "type": [ "string", "null" ], "example": null }, "privacy_policy_url": { "type": [ "string", "null" ], "example": "https://fizjo-pro.pl/privacy" }, "expires_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" } }, "required": [ "name", "email", "tenant_name", "tenant_logo_url", "privacy_policy_url", "expires_at" ] } } } }, "400": { "description": "Invalid or expired state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/apple/authorize": { "get": { "tags": [ "Apple OAuth" ], "summary": "Initiate Apple Sign In flow", "operationId": "getAppleOAuthAuthorize", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tenant_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tenant_slug", "in": "query" }, { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "oauth_state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_client_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "oauth_code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "oauth_scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_resource", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "oauth_resume_binding", "in": "query" } ], "responses": { "302": { "description": "Redirect to Apple authorization endpoint" }, "400": { "description": "Invalid redirect_uri or missing tenant identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found or Apple Sign In not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "State table DoS limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/callback/apple": { "post": { "tags": [ "Apple OAuth" ], "summary": "Apple Sign In callback (form-post)", "operationId": "postAppleOAuthCallback", "responses": { "302": { "description": "Redirect with tokens or to consent page" }, "400": { "description": "Invalid state or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/apple/consent": { "post": { "tags": [ "Apple OAuth" ], "summary": "Accept consent and create user via Apple Sign In", "operationId": "postAppleOAuthConsent", "responses": { "302": { "description": "Redirect with tokens to consumer app" }, "400": { "description": "Invalid or expired state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/apple/consent-state": { "get": { "tags": [ "Apple OAuth" ], "summary": "Fetch consent preview data for Apple Sign In consent interstitial", "operationId": "getAppleConsentState", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Consent state token" }, "required": true, "description": "Consent state token", "name": "state", "in": "query" } ], "responses": { "200": { "description": "Consent preview data", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "example": "Anna Kowalska" }, "email": { "type": "string", "example": "anna@example.com" }, "tenant_name": { "type": "string", "example": "Fizjo Pro" }, "tenant_logo_url": { "type": [ "string", "null" ], "example": null }, "privacy_policy_url": { "type": [ "string", "null" ], "example": "https://fizjo-pro.pl/privacy" }, "expires_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" } }, "required": [ "name", "email", "tenant_name", "tenant_logo_url", "privacy_policy_url", "expires_at" ] } } } }, "400": { "description": "Invalid or expired state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/discord/authorize": { "get": { "tags": [ "Discord OAuth" ], "summary": "Initiate Discord OAuth flow", "operationId": "getDiscordOAuthAuthorize", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tenant_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tenant_slug", "in": "query" }, { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "login_hint", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "oauth_state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_client_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "oauth_code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "oauth_scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_resource", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "oauth_resume_binding", "in": "query" } ], "responses": { "302": { "description": "Redirect to Discord authorization endpoint" }, "400": { "description": "Invalid redirect_uri or missing tenant identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found or Discord OAuth not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "State table DoS limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Provider temporarily disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/callback/discord": { "get": { "tags": [ "Discord OAuth" ], "summary": "Discord OAuth callback", "operationId": "getDiscordOAuthCallback", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error_description", "in": "query" } ], "responses": { "302": { "description": "Redirect with tokens or to consent page" }, "400": { "description": "Invalid state or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/discord/consent": { "post": { "tags": [ "Discord OAuth" ], "summary": "Process Discord OAuth consent", "operationId": "postDiscordOAuthConsent", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "consent_token": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" } }, "required": [ "consent_token", "tenant_id" ] } } } }, "responses": { "302": { "description": "Redirect with tokens after user creation" }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/discord/consent/state": { "get": { "tags": [ "Discord OAuth" ], "summary": "Get Discord OAuth consent state", "operationId": "getDiscordOAuthConsentState", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "consent_token", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Provider claims for consent form", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "email_trust": { "type": "string", "enum": [ "provider_verified", "always_verified", "never_trust" ] } }, "required": [ "email", "name", "provider" ] } } } }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/facebook/authorize": { "get": { "tags": [ "Facebook OAuth" ], "summary": "Initiate Facebook OAuth flow", "operationId": "getFacebookOAuthAuthorize", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tenant_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tenant_slug", "in": "query" }, { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "login_hint", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "oauth_state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_client_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "oauth_code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "oauth_scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_resource", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "oauth_resume_binding", "in": "query" } ], "responses": { "302": { "description": "Redirect to Facebook authorization endpoint" }, "400": { "description": "Invalid redirect_uri or missing tenant identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found or Facebook OAuth not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "State table DoS limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Provider temporarily disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/callback/facebook": { "get": { "tags": [ "Facebook OAuth" ], "summary": "Facebook OAuth callback", "operationId": "getFacebookOAuthCallback", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error_description", "in": "query" } ], "responses": { "302": { "description": "Redirect with tokens or to consent page" }, "400": { "description": "Invalid state or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/facebook/consent": { "post": { "tags": [ "Facebook OAuth" ], "summary": "Process Facebook OAuth consent", "operationId": "postFacebookOAuthConsent", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "consent_token": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" } }, "required": [ "consent_token", "tenant_id" ] } } } }, "responses": { "302": { "description": "Redirect with tokens after user creation" }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/facebook/consent/state": { "get": { "tags": [ "Facebook OAuth" ], "summary": "Get Facebook OAuth consent state", "operationId": "getFacebookOAuthConsentState", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "consent_token", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Provider claims for consent form", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "email_trust": { "type": "string", "enum": [ "provider_verified", "always_verified", "never_trust" ] } }, "required": [ "email", "name", "provider" ] } } } }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/slack/authorize": { "get": { "tags": [ "Slack OAuth" ], "summary": "Initiate Slack OAuth flow", "operationId": "getSlackOAuthAuthorize", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tenant_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tenant_slug", "in": "query" }, { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "login_hint", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "oauth_state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_client_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "oauth_code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "oauth_scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_resource", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "oauth_resume_binding", "in": "query" } ], "responses": { "302": { "description": "Redirect to Slack authorization endpoint" }, "400": { "description": "Invalid redirect_uri or missing tenant identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found or Slack OAuth not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "State table DoS limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Provider temporarily disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/callback/slack": { "get": { "tags": [ "Slack OAuth" ], "summary": "Slack OAuth callback", "operationId": "getSlackOAuthCallback", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error_description", "in": "query" } ], "responses": { "302": { "description": "Redirect with tokens or to consent page" }, "400": { "description": "Invalid state or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/slack/consent": { "post": { "tags": [ "Slack OAuth" ], "summary": "Process Slack OAuth consent", "operationId": "postSlackOAuthConsent", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "consent_token": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" } }, "required": [ "consent_token", "tenant_id" ] } } } }, "responses": { "302": { "description": "Redirect with tokens after user creation" }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/slack/consent/state": { "get": { "tags": [ "Slack OAuth" ], "summary": "Get Slack OAuth consent state", "operationId": "getSlackOAuthConsentState", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "consent_token", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Provider claims for consent form", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "email_trust": { "type": "string", "enum": [ "provider_verified", "always_verified", "never_trust" ] } }, "required": [ "email", "name", "provider" ] } } } }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/twitter/authorize": { "get": { "tags": [ "Twitter/X OAuth" ], "summary": "Initiate Twitter/X OAuth flow", "operationId": "getTwitterOAuthAuthorize", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tenant_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tenant_slug", "in": "query" }, { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "login_hint", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "oauth_state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_client_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "oauth_code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "oauth_scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_resource", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "oauth_resume_binding", "in": "query" } ], "responses": { "302": { "description": "Redirect to Twitter/X authorization endpoint" }, "400": { "description": "Invalid redirect_uri or missing tenant identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found or Twitter/X OAuth not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "State table DoS limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Provider temporarily disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/callback/twitter": { "get": { "tags": [ "Twitter/X OAuth" ], "summary": "Twitter/X OAuth callback", "operationId": "getTwitterOAuthCallback", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error_description", "in": "query" } ], "responses": { "302": { "description": "Redirect with tokens or to consent page" }, "400": { "description": "Invalid state or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/twitter/consent": { "post": { "tags": [ "Twitter/X OAuth" ], "summary": "Process Twitter/X OAuth consent", "operationId": "postTwitterOAuthConsent", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "consent_token": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" } }, "required": [ "consent_token", "tenant_id" ] } } } }, "responses": { "302": { "description": "Redirect with tokens after user creation" }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/twitter/consent/state": { "get": { "tags": [ "Twitter/X OAuth" ], "summary": "Get Twitter/X OAuth consent state", "operationId": "getTwitterOAuthConsentState", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "consent_token", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Provider claims for consent form", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "email_trust": { "type": "string", "enum": [ "provider_verified", "always_verified", "never_trust" ] } }, "required": [ "email", "name", "provider" ] } } } }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/gitlab/authorize": { "get": { "tags": [ "GitLab OAuth" ], "summary": "Initiate GitLab OAuth flow", "operationId": "getGitlabOAuthAuthorize", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tenant_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tenant_slug", "in": "query" }, { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "login_hint", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "oauth_state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_client_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "oauth_code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "oauth_scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_resource", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "oauth_resume_binding", "in": "query" } ], "responses": { "302": { "description": "Redirect to GitLab authorization endpoint" }, "400": { "description": "Invalid redirect_uri or missing tenant identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found or GitLab OAuth not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "State table DoS limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Provider temporarily disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/callback/gitlab": { "get": { "tags": [ "GitLab OAuth" ], "summary": "GitLab OAuth callback", "operationId": "getGitlabOAuthCallback", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error_description", "in": "query" } ], "responses": { "302": { "description": "Redirect with tokens or to consent page" }, "400": { "description": "Invalid state or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/gitlab/consent": { "post": { "tags": [ "GitLab OAuth" ], "summary": "Process GitLab OAuth consent", "operationId": "postGitlabOAuthConsent", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "consent_token": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" } }, "required": [ "consent_token", "tenant_id" ] } } } }, "responses": { "302": { "description": "Redirect with tokens after user creation" }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/gitlab/consent/state": { "get": { "tags": [ "GitLab OAuth" ], "summary": "Get GitLab OAuth consent state", "operationId": "getGitlabOAuthConsentState", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "consent_token", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Provider claims for consent form", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "email_trust": { "type": "string", "enum": [ "provider_verified", "always_verified", "never_trust" ] } }, "required": [ "email", "name", "provider" ] } } } }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/linkedin/authorize": { "get": { "tags": [ "LinkedIn OAuth" ], "summary": "Initiate LinkedIn OAuth flow", "operationId": "getLinkedinOAuthAuthorize", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tenant_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tenant_slug", "in": "query" }, { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "redirect_uri", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "login_hint", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "oauth_state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_client_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "oauth_code_challenge", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_code_challenge_method", "in": "query" }, { "schema": { "type": "string", "maxLength": 256 }, "required": false, "name": "oauth_scope", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "oauth_resource", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "oauth_resume_binding", "in": "query" } ], "responses": { "302": { "description": "Redirect to LinkedIn authorization endpoint" }, "400": { "description": "Invalid redirect_uri or missing tenant identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found or LinkedIn OAuth not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "State table DoS limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Provider temporarily disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/callback/linkedin": { "get": { "tags": [ "LinkedIn OAuth" ], "summary": "LinkedIn OAuth callback", "operationId": "getLinkedinOAuthCallback", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error_description", "in": "query" } ], "responses": { "302": { "description": "Redirect with tokens or to consent page" }, "400": { "description": "Invalid state or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/linkedin/consent": { "post": { "tags": [ "LinkedIn OAuth" ], "summary": "Process LinkedIn OAuth consent", "operationId": "postLinkedinOAuthConsent", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "consent_token": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" } }, "required": [ "consent_token", "tenant_id" ] } } } }, "responses": { "302": { "description": "Redirect with tokens after user creation" }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/oauth/linkedin/consent/state": { "get": { "tags": [ "LinkedIn OAuth" ], "summary": "Get LinkedIn OAuth consent state", "operationId": "getLinkedinOAuthConsentState", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "consent_token", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Provider claims for consent form", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "email_trust": { "type": "string", "enum": [ "provider_verified", "always_verified", "never_trust" ] } }, "required": [ "email", "name", "provider" ] } } } }, "400": { "description": "Invalid consent token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/me/grants": { "get": { "tags": [ "Auth" ], "summary": "List OAuth applications authorized by the current user", "operationId": "listMyGrants", "responses": { "200": { "description": "The applications you have authorized, oldest authorization first. This response carries at most a fixed maximum number of applications; when more exist, `truncated` is true and the remaining applications are NOT retrievable through this endpoint, which offers no pagination cursor. Branch on `truncated` — do not treat `data` as the complete set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "01912345-abcd-7def-8901-234567890abc" }, "app_name": { "type": "string", "example": "My Web App" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "read", "write" ] }, "authorized_at": { "type": "string", "format": "date-time", "example": "2026-03-07T12:00:00.000Z" }, "auto_granted": { "type": "boolean", "description": "True if consent was auto-granted via skip_consent" }, "app_logo_url": { "type": "string", "example": "https://example.com/logo.png" }, "resources": { "type": "array", "items": { "type": "string" }, "example": [ "https://api.third-party.example" ] }, "agent_scopes": { "type": "array", "items": { "type": "string" }, "example": [ "mcp:tools:read" ] }, "agent_scopes_reviewed_at": { "type": "string", "format": "date-time", "description": "When the user last confirmed they reviewed this application’s agent capabilities (RFC 3339 date-time). Absent when they never have.", "example": "2026-03-07T12:00:00.000Z" }, "next_review_due_at": { "type": "string", "format": "date-time", "description": "When this application’s agent capabilities next come up for the periodic review reminder (RFC 3339 date-time). Absent when the grant carries no agent capabilities. This is a review cadence, not an expiry: nothing lapses on this date and the authorization is never withdrawn automatically.", "example": "2026-09-03T12:00:00.000Z" } }, "required": [ "id", "app_name", "scopes", "authorized_at", "auto_granted" ] } }, "truncated": { "type": "boolean", "description": "True when more authorized applications exist than this response carries. The cut is explicit rather than silent; the list is ordered oldest authorization first.", "example": false } }, "required": [ "data", "truncated" ] } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "MFA verification required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/me/grants/{id}": { "delete": { "tags": [ "Auth" ], "summary": "Revoke an OAuth application grant", "operationId": "revokeMyGrant", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Grant revoked successfully" }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "MFA verification required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Grant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/me/grants/{id}/capability-review": { "post": { "tags": [ "Auth" ], "summary": "Confirm you have reviewed an application’s agent capabilities", "description": "Records that you looked at the agent capabilities this application holds, and moves the next review reminder forward. This is an attestation only: it does not grant, extend or re-issue anything, and it never changes what the application may do.", "operationId": "recordMyGrantCapabilityReview", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Review recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_scopes_reviewed_at": { "type": "string", "format": "date-time" }, "next_review_due_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "agent_scopes_reviewed_at", "next_review_due_at" ] } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "MFA verification required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Grant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/me/organizations": { "get": { "tags": [ "Organizations" ], "summary": "List the authenticated user's org memberships (Accounts self-service)", "operationId": "listMyOrganizations", "responses": { "200": { "description": "Memberships", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeOrgMembership" } } }, "required": [ "data" ] } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "MFA verification required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/me/organizations/invitations": { "get": { "tags": [ "Organizations" ], "summary": "List the authenticated user's pending org invitations (Accounts self-service)", "operationId": "listMyPendingOrgInvitations", "responses": { "200": { "description": "Pending invitations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MePendingOrgInvitation" } } }, "required": [ "data" ] } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "MFA verification required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/me/organizations/invitations/{id}/accept": { "post": { "tags": [ "Organizations" ], "summary": "Accept one of my pending org invitations by id (Accounts self-service)", "operationId": "acceptMyOrgInvitation", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Invitation accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string" }, "role": { "type": "string" } }, "required": [ "org_id", "role" ] } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "MFA verification required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Invitation not found, not yours, or already used", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Already a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "Invitation expired or already used", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/auth/me/organizations/invitations/{id}": { "delete": { "tags": [ "Organizations" ], "summary": "Decline one of my pending org invitations by id (Accounts self-service)", "operationId": "declineMyOrgInvitation", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Declined (or already declined — idempotent)" }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "MFA verification required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Invitation not found, not yours, or wrong tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Invitation already accepted/superseded — cannot decline", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/import/preview": { "post": { "tags": [ "Users" ], "summary": "Preview user import (validate CSV/JSON without creating users)", "operationId": "previewImportUsers", "responses": { "200": { "description": "Import preview with validation results", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview_rows": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "has_password_hash": { "type": "boolean" }, "validation_status": { "type": "string", "enum": [ "valid", "warning" ] }, "hash_warning": { "type": "string" } }, "required": [ "email", "has_password_hash", "validation_status" ] } }, "total_rows": { "type": "number" }, "valid_count": { "type": "number" }, "error_count": { "type": "number" }, "error_percentage": { "type": "number" }, "headers": { "type": "array", "items": { "type": "string" } }, "discarded_columns": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "number" }, "email": { "type": [ "string", "null" ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "row", "email", "error", "code" ] } }, "hash_statistics": { "type": "object", "properties": { "argon2id": { "type": "number" }, "bcrypt": { "type": "number" }, "no_hash": { "type": "number" }, "unsupported": { "type": "number" } }, "required": [ "argon2id", "bcrypt", "no_hash", "unsupported" ] } }, "required": [ "preview_rows", "total_rows", "valid_count", "error_count", "error_percentage", "headers", "discarded_columns", "errors", "hash_statistics" ] } } } }, "400": { "description": "Invalid file or data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "File too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/import": { "post": { "tags": [ "Users" ], "summary": "Import users from CSV file or JSON array", "operationId": "importUsers", "parameters": [ { "schema": { "type": "string", "enum": [ "consent", "contract", "legitimate_interest" ], "description": "GDPR legal basis for processing" }, "required": true, "description": "GDPR legal basis for processing", "name": "legal_basis", "in": "query" }, { "schema": { "type": "string", "description": "Error threshold (1-50, default 10)" }, "required": false, "description": "Error threshold (1-50, default 10)", "name": "max_error_percentage", "in": "query" } ], "responses": { "201": { "description": "Users imported successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "import_session_id": { "type": "string" }, "success_count": { "type": "number" }, "new_user_count": { "type": "number" }, "passwordless_count": { "type": "number" }, "failed_count": { "type": "number" }, "warning_count": { "type": "number" }, "failed_records": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "number" }, "email": { "type": "string" }, "error": { "type": "string" } }, "required": [ "row", "email", "error" ] } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "number" }, "email": { "type": "string" }, "warning": { "type": "string" } }, "required": [ "row", "email", "warning" ] } }, "hash_statistics": { "type": "object", "properties": { "argon2id": { "type": "number" }, "bcrypt": { "type": "number" }, "no_hash": { "type": "number" }, "unsupported": { "type": "number" } }, "required": [ "argon2id", "bcrypt", "no_hash", "unsupported" ] } }, "required": [ "import_session_id", "success_count", "new_user_count", "passwordless_count", "failed_count", "warning_count", "failed_records", "warnings" ] } } } }, "400": { "description": "Invalid file, threshold exceeded, or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "File too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/{userId}": { "get": { "tags": [ "Users" ], "summary": "Get an end-user by ID", "description": "Returns details for a specific end-user. Requires a valid API key with read:users scope.", "operationId": "getUser", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "User ID (UUID)", "example": "01912345-abcd-7def-8901-234567890abc" }, "required": true, "description": "User ID (UUID)", "name": "userId", "in": "path" } ], "responses": { "200": { "description": "User details", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "example": "01912345-abcd-7def-8901-234567890abc" }, "email": { "type": "string", "example": "user@example.com" }, "status": { "type": "string", "enum": [ "active", "blocked", "unverified" ] }, "email_verified": { "type": "boolean" }, "import_source": { "type": "string", "example": "csv_upload" }, "last_login_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" }, "created_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" }, "blocked_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" }, "mfa_enabled": { "type": "boolean", "example": false }, "mfa_method": { "type": "string", "example": "totp" }, "mfa_enabled_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" } }, "required": [ "user_id", "email", "status", "email_verified", "created_at", "mfa_enabled" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "423": { "description": "Tenant pending deletion", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Users" ], "summary": "Delete an end-user with GDPR Art. 17 deletion certificate", "operationId": "deleteUser", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "User ID to delete" }, "required": true, "description": "User ID to delete", "name": "userId", "in": "path" } ], "responses": { "200": { "description": "User deleted with deletion certificate", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "certificate": { "type": "object", "properties": { "certificate_id": { "type": "string", "format": "uuid" }, "entity_type": { "type": "string", "enum": [ "user", "tenant" ] }, "entity_id": { "type": "string", "format": "uuid" }, "deleted_at": { "type": "string", "format": "date-time" }, "deleted_by": { "type": "string" }, "data_types_deleted": { "type": "array", "items": { "type": "string" } }, "data_retained": { "type": "array", "items": { "type": "string" } }, "hash": { "type": "string" } }, "required": [ "certificate_id", "entity_type", "entity_id", "deleted_at", "deleted_by", "data_types_deleted", "data_retained", "hash" ] } }, "required": [ "deleted", "certificate" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Cannot delete self or last owner", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "423": { "description": "Tenant pending deletion", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Users" ], "summary": "Update an end-user (email change with GDPR Art. 16 rectification)", "operationId": "updateUser", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "User ID to update" }, "required": true, "description": "User ID to update", "name": "userId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "new@example.com" }, "skip_verification": { "type": "boolean", "default": false, "example": false } } } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "example": "01912345-abcd-7def-8901-234567890abc" }, "email": { "type": "string", "example": "user@example.com" }, "status": { "type": "string", "enum": [ "active", "blocked", "unverified" ] }, "email_verified": { "type": "boolean" }, "last_login_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" }, "created_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" }, "blocked_at": { "type": "string", "example": "2026-03-07T12:00:00.000Z" } }, "required": [ "user_id", "email", "status", "email_verified", "created_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Email already in use", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/{userId}/metadata": { "get": { "tags": [ "Users" ], "summary": "Get user metadata", "description": "Returns public and private metadata for a specific user. Emits an audit log entry when private_metadata is returned.", "operationId": "getUserMetadata", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "User ID (UUID)", "example": "01912345-abcd-7def-8901-234567890abc" }, "required": true, "description": "User ID (UUID)", "name": "userId", "in": "path" } ], "responses": { "200": { "description": "User metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "public_metadata": { "type": "object", "additionalProperties": {}, "description": "Public metadata (visible in JWT access tokens up to 1 KB)." }, "private_metadata": { "type": "object", "additionalProperties": {}, "description": "Private metadata (admin-only, never included in tokens)." } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Users" ], "summary": "Patch user metadata", "description": "Shallow-merge custom metadata onto a user. Set a key to null to delete it. Enforces plan limits (Free: 5 keys / 4 KB; Pro+: 64 KB).", "operationId": "patchUserMetadata", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "User ID (UUID)", "example": "01912345-abcd-7def-8901-234567890abc" }, "required": true, "description": "User ID (UUID)", "name": "userId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "public_metadata": { "type": "object", "additionalProperties": {}, "description": "Public metadata (shallow merge). Set key to null to delete it. Visible in JWT access tokens up to 1 KB." }, "private_metadata": { "type": "object", "additionalProperties": {}, "description": "Private metadata (shallow merge). Set key to null to delete it. Admin-only, never included in tokens." } } } } } }, "responses": { "200": { "description": "Updated user with metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "example": "01912345-abcd-7def-8901-234567890abc" }, "email": { "type": "string", "example": "user@example.com" }, "status": { "type": "string", "enum": [ "active", "blocked", "unverified" ] }, "email_verified": { "type": "boolean" }, "import_source": { "type": "string" }, "last_login_at": { "type": "string" }, "created_at": { "type": "string" }, "blocked_at": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "public_metadata": { "type": "object", "additionalProperties": {}, "description": "Public user metadata" }, "private_metadata": { "type": "object", "additionalProperties": {}, "description": "Private user metadata" } }, "required": [ "user_id", "email", "status", "email_verified", "created_at", "mfa_enabled" ] } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope or plan limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/{fromUserId}/flag-membership-transfer-preview": { "get": { "tags": [ "Users" ], "summary": "Preview feature-flag user_list memberships an account merge would transfer", "operationId": "previewFlagMembershipTransfer", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Merged-FROM user id" }, "required": true, "description": "Merged-FROM user id", "name": "fromUserId", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Surviving (TO) user id" }, "required": true, "description": "Surviving (TO) user id", "name": "to", "in": "query" } ], "responses": { "200": { "description": "Affected flags + per-rule dedupe preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected_flags": { "type": "array", "items": { "type": "object", "properties": { "flag_id": { "type": "string", "format": "uuid" }, "flag_key": { "type": "string" }, "rule_index": { "type": "integer", "minimum": 0 }, "will_transfer_default": { "type": "boolean" }, "to_user_already_member": { "type": "boolean" }, "collapses": { "type": "boolean" } }, "required": [ "flag_id", "flag_key", "rule_index", "will_transfer_default", "to_user_already_member", "collapses" ] } }, "affected_count": { "type": "integer", "minimum": 0 } }, "required": [ "affected_flags", "affected_count" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User not found (cross-tenant / cross-env)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/{fromUserId}/flag-membership-transfer": { "post": { "tags": [ "Users" ], "summary": "Transfer feature-flag user_list membership from a merged user onto the survivor", "operationId": "transferFlagMembership", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Merged-FROM user id" }, "required": true, "description": "Merged-FROM user id", "name": "fromUserId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_user_id": { "type": "string", "format": "uuid" }, "merge_id": { "type": "string", "format": "uuid" }, "flag_decisions": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "required": [ "to_user_id", "merge_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Membership transferred (or idempotent replay)", "content": { "application/json": { "schema": { "type": "object", "properties": { "transferred": { "type": "boolean" }, "summary": { "type": "object", "properties": { "affected_flags": { "type": "integer", "minimum": 0 }, "transferred_flags": { "type": "integer", "minimum": 0 }, "declined_flags": { "type": "integer", "minimum": 0 }, "already_transferred_flags": { "type": "integer", "minimum": 0 }, "malformed_flags": { "type": "integer", "minimum": 0 }, "emit_failures": { "type": "integer", "minimum": 0 }, "replayed": { "type": "boolean" }, "flag_summaries": { "type": "array", "items": { "type": "object", "properties": { "flag_id": { "type": "string", "format": "uuid" }, "flag_key": { "type": "string" }, "transferred": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "transferred", "skipped_by_decision", "already_transferred", "malformed" ] } }, "required": [ "flag_id", "flag_key", "transferred", "reason" ] } } }, "required": [ "affected_flags", "transferred_flags", "declined_flags", "already_transferred_flags", "malformed_flags", "emit_failures", "replayed", "flag_summaries" ] } }, "required": [ "transferred", "summary" ] } } } }, "400": { "description": "Validation error / self-transfer", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User not found (cross-tenant / cross-env)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/ciba/request": { "get": { "tags": [ "Users" ], "summary": "Read a pending CIBA authentication request (decision-page display data)", "operationId": "getUsersMeCibaRequest", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "required": true, "name": "token", "in": "query" } ], "responses": { "200": { "description": "Pending request details", "content": { "application/json": { "schema": { "type": "object", "properties": { "binding_message": { "type": "string" }, "binding_message_locale": { "type": "string" }, "resource": { "type": "string" }, "resource_host": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "binding_message", "expires_at" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found (incl. cross-user collapse)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Already decided", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "Expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/ciba/decision": { "post": { "tags": [ "Users" ], "summary": "Approve or deny a pending CIBA authentication request", "operationId": "postUsersMeCibaDecision", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url_token": { "type": "string", "minLength": 1, "maxLength": 256 }, "decision": { "type": "string", "enum": [ "approve", "deny" ] } }, "required": [ "url_token", "decision" ] } } } }, "responses": { "200": { "description": "Decision recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approved", "denied" ] } }, "required": [ "status" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Cross-user access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Already decided", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "Expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/notifications": { "get": { "tags": [ "Users" ], "summary": "List dashboard notifications for the authenticated user", "operationId": "getUsersMeNotifications", "parameters": [ { "schema": { "type": [ "boolean", "null" ] }, "required": false, "name": "unread_only", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "payload": { "type": "object", "additionalProperties": {} }, "unread": { "type": "boolean" }, "created_at": { "type": "string" }, "read_at": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "payload", "unread", "created_at", "read_at" ] } }, "unread_count": { "type": "integer" } }, "required": [ "items", "unread_count" ] } } } } } } }, "/v1/roles": { "post": { "tags": [ "RBAC Roles" ], "summary": "Create a custom role", "operationId": "createRole", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100, "pattern": "^[a-zA-Z][a-zA-Z0-9_ -]{0,98}[a-zA-Z0-9]$", "description": "Role display name", "example": "Team Admin" }, "key": { "type": "string", "minLength": 2, "maxLength": 100, "pattern": "^[a-z][a-z0-9_]{0,98}[a-z0-9]$", "description": "Immutable role key (auto-generated from name if omitted). If the generated key collides with an existing role key, a numeric suffix is appended automatically (e.g. team_admin → team_admin_2).", "example": "team_admin" }, "description": { "type": "string", "maxLength": 500, "description": "Role description" }, "permissions": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 100, "pattern": "^[a-z][a-z0-9_]*:(\\*|[a-z][a-z0-9_*]*)$" }, "maxItems": 1000, "default": [], "description": "Permission strings", "example": [ "posts:read", "posts:write" ] }, "reason": { "type": "string", "maxLength": 500, "description": "Audit reason for role creation" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Role created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_builtin": { "type": "boolean" }, "permissions": { "type": "array", "items": { "type": "string" } }, "permission_count": { "type": "number" }, "assigned_user_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "name", "is_builtin", "permissions", "permission_count", "assigned_user_count", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid input or reserved name", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit reached or insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "A role with this name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "RBAC Roles" ], "summary": "List all roles", "operationId": "listRoles", "responses": { "200": { "description": "List of roles (built-in + custom)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_builtin": { "type": "boolean" }, "permissions": { "type": "array", "items": { "type": "string" } }, "permission_count": { "type": "number" }, "assigned_user_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "name", "is_builtin", "permissions", "permission_count", "assigned_user_count", "created_at", "updated_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/roles/{id}": { "get": { "tags": [ "RBAC Roles" ], "summary": "Get a role by ID", "operationId": "getRole", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Role ID" }, "required": true, "description": "Role ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Role details with full permission list", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_builtin": { "type": "boolean" }, "permissions": { "type": "array", "items": { "type": "string" } }, "permission_count": { "type": "number" }, "assigned_user_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "name", "is_builtin", "permissions", "permission_count", "assigned_user_count", "created_at", "updated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Role not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "RBAC Roles" ], "summary": "Update a custom role", "operationId": "updateRole", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Role ID" }, "required": true, "description": "Role ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100, "pattern": "^[a-zA-Z][a-zA-Z0-9_ -]{0,98}[a-zA-Z0-9]$", "description": "New role display name" }, "key": { "type": "string", "description": "Role key (immutable — always rejected with 400)" }, "description": { "type": "string", "maxLength": 500, "description": "New role description" }, "permissions": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 100, "pattern": "^[a-z][a-z0-9_]*:(\\*|[a-z][a-z0-9_*]*)$" }, "maxItems": 1000, "description": "Full permission replace" }, "permissions_add": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 100, "pattern": "^[a-z][a-z0-9_]*:(\\*|[a-z][a-z0-9_*]*)$" }, "maxItems": 1000, "description": "Permissions to add (incremental)" }, "permissions_remove": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 100, "pattern": "^[a-z][a-z0-9_]*:(\\*|[a-z][a-z0-9_*]*)$" }, "maxItems": 1000, "description": "Permissions to remove (incremental)" }, "reason": { "type": "string", "maxLength": 500, "description": "Audit reason for role update" } } } } } }, "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_builtin": { "type": "boolean" }, "permissions": { "type": "array", "items": { "type": "string" } }, "permission_count": { "type": "number" }, "assigned_user_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "name", "is_builtin", "permissions", "permission_count", "assigned_user_count", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid input, builtin immutable, or key immutable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit reached or insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Role not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "RBAC Roles" ], "summary": "Delete a custom role", "operationId": "deleteRole", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Role ID" }, "required": true, "description": "Role ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "true" ], "description": "Force delete with user reassignment cleanup" }, "required": false, "description": "Force delete with user reassignment cleanup", "name": "force", "in": "query" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "string", "description": "Confirmation string for force delete", "example": "delete-role-and-assignments" }, "reason": { "type": "string", "maxLength": 500, "description": "Audit reason for role deletion" } } } } } }, "responses": { "204": { "description": "Role deleted" }, "400": { "description": "Cannot delete built-in role or missing confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Role not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Role has user assignments", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/permissions": { "get": { "tags": [ "RBAC Roles" ], "summary": "List all unique permissions across tenant roles", "operationId": "listPermissions", "responses": { "200": { "description": "Deduplicated, sorted list of all permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/{id}/roles": { "post": { "tags": [ "RBAC User Roles" ], "summary": "Assign a role to a user", "operationId": "assignUserRole", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "User ID" }, "required": true, "description": "User ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role_id": { "type": "string", "format": "uuid", "description": "Role ID to assign" }, "role_key": { "type": "string", "minLength": 2, "maxLength": 100, "description": "Role key to assign (alternative to role_id)" }, "reason": { "type": "string", "maxLength": 500, "description": "Audit reason for assignment" } } } } } }, "responses": { "201": { "description": "Role assigned", "content": { "application/json": { "schema": { "type": "object", "properties": { "role_id": { "type": "string" }, "role_key": { "type": "string" }, "role_name": { "type": "string" }, "assigned_at": { "type": "string" } }, "required": [ "role_id", "role_key", "role_name", "assigned_at" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User or role not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "RBAC User Roles" ], "summary": "List roles assigned to a user", "operationId": "listUserRoles", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "User ID" }, "required": true, "description": "User ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "List of roles assigned to the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "role_id": { "type": "string" }, "role_key": { "type": "string" }, "role_name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "assigned_at": { "type": "string" }, "assigned_by": { "type": "string" }, "assigned_via": { "type": "string" } }, "required": [ "role_id", "role_key", "role_name", "permissions", "assigned_at", "assigned_via" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/{id}/roles/{roleId}": { "delete": { "tags": [ "RBAC User Roles" ], "summary": "Remove a role from a user", "operationId": "removeUserRole", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "User ID" }, "required": true, "description": "User ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Role ID" }, "required": true, "description": "Role ID", "name": "roleId", "in": "path" } ], "responses": { "204": { "description": "Role removed" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User, role, or assignment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections": { "get": { "tags": [ "SSO" ], "summary": "List SSO connections", "operationId": "listSsoConnections", "parameters": [ { "schema": { "type": "string", "description": "Pagination cursor (next_cursor from previous response)" }, "required": false, "description": "Pagination cursor (next_cursor from previous response)", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List of SSO connections", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "last_used_at": { "type": "string" }, "idp_certificate_expires_at": { "type": "string" }, "idp_certificate_days_until_expiry": { "type": "integer" }, "error_message": { "type": "string" }, "users_count": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "type", "status", "users_count", "created_at", "updated_at" ] } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "required": [ "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "SSO" ], "summary": "Create an SSO connection", "operationId": "createSsoConnection", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "saml", "oidc" ], "description": "Connection type" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Unique connection name within tenant" }, "idp_config": { "type": "object", "additionalProperties": {}, "description": "IdP configuration (type-specific)" }, "attribute_mapping": { "type": "object", "additionalProperties": {} }, "settings": { "type": "object", "properties": { "jit_provisioning_enabled": { "type": "boolean" }, "attribute_update_mode": { "type": "string", "enum": [ "always", "first_login_only" ] }, "jit_require_group": { "type": [ "string", "null" ], "minLength": 1 }, "jit_default_role": { "type": [ "string", "null" ], "minLength": 1 } }, "additionalProperties": {} }, "idp_metadata_url": { "type": "string", "format": "uri", "description": "SAML IdP metadata URL (auto-parsed)" } }, "required": [ "type", "name", "idp_config" ] } } } }, "responses": { "201": { "description": "Connection created (client_secret shown once for OIDC)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Connection name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid IdP config or SSRF blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections/:id": { "get": { "tags": [ "SSO" ], "summary": "Get SSO connection details", "operationId": "getSsoConnection", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "SSO connection details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "SSO" ], "summary": "Update an SSO connection", "operationId": "updateSsoConnection", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "idp_config": { "type": "object", "additionalProperties": {} }, "attribute_mapping": { "type": "object", "additionalProperties": {} }, "settings": { "type": "object", "properties": { "jit_provisioning_enabled": { "type": "boolean" }, "attribute_update_mode": { "type": "string", "enum": [ "always", "first_login_only" ] }, "jit_require_group": { "type": [ "string", "null" ], "minLength": 1 }, "jit_default_role": { "type": [ "string", "null" ], "minLength": 1 } }, "additionalProperties": {} }, "idp_metadata_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "Updated connection", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid config or SSRF blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "SSO" ], "summary": "Delete an SSO connection", "operationId": "deleteSsoConnection", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Connection deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections/:id/status": { "patch": { "tags": [ "SSO" ], "summary": "Activate or deactivate an SSO connection", "operationId": "updateSsoConnectionStatus", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Target status (error cannot be set via API)" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Updated connection", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid status transition (e.g. cannot set error via API)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections/:id/test": { "post": { "tags": [ "SSO" ], "summary": "Test SSO connection configuration (non-live validation)", "operationId": "testSsoConnection", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Test results (always 200 — errors in checks payload)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "passed": { "type": "boolean" }, "message": { "type": "string" }, "level": { "type": "string", "enum": [ "error", "warning" ] } }, "required": [ "name", "passed" ] } } }, "required": [ "ok", "checks" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections/:connectionId/domains": { "post": { "tags": [ "SSO" ], "summary": "Add email domain routing to an SSO connection", "operationId": "addSsoDomain", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "connectionId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 253 } }, "required": [ "domain" ] } } } }, "responses": { "201": { "description": "Domain added", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "connection_id": { "type": "string" }, "domain": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "connection_id", "domain", "created_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Domain already registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid domain format", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "SSO" ], "summary": "List email domain routing for an SSO connection", "operationId": "listSsoDomains", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "connectionId", "in": "path" } ], "responses": { "200": { "description": "Domain list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connection_id": { "type": "string" }, "domain": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "connection_id", "domain", "created_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections/:connectionId/domains/:domainId": { "delete": { "tags": [ "SSO" ], "summary": "Remove email domain routing from an SSO connection", "operationId": "removeSsoDomain", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "connectionId", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "domainId", "in": "path" } ], "responses": { "204": { "description": "Domain removed" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/resolve-domain": { "get": { "tags": [ "SSO" ], "summary": "Resolve an email address to its SSO connection", "operationId": "resolveSsoDomain", "parameters": [ { "schema": { "type": "string", "format": "email" }, "required": true, "name": "email", "in": "query" } ], "responses": { "200": { "description": "SSO connection for this email domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "connection_id", "type", "name" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No SSO connection for this email domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections/:connectionId/bypass-codes": { "post": { "tags": [ "SSO" ], "summary": "Generate emergency bypass codes for an SSO connection", "operationId": "generateBypassCodes", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "connectionId", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } } } } } }, "responses": { "201": { "description": "Generated bypass codes (shown once — store securely)", "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" } }, "expires_in_days": { "type": "number" } }, "required": [ "codes", "expires_in_days" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid count", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "SSO" ], "summary": "Revoke all unused emergency bypass codes for an SSO connection", "operationId": "revokeBypassCodes", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "connectionId", "in": "path" } ], "responses": { "204": { "description": "All unused codes revoked" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections/:connectionId/bypass-codes/count": { "get": { "tags": [ "SSO" ], "summary": "Count unused bypass codes for an SSO connection", "operationId": "countBypassCodes", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "connectionId", "in": "path" } ], "responses": { "200": { "description": "Count of unused bypass codes", "content": { "application/json": { "schema": { "type": "object", "properties": { "unused_count": { "type": "number" } }, "required": [ "unused_count" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/emergency-login": { "post": { "tags": [ "SSO" ], "summary": "Emergency login using a bypass code when SSO enforcement is active", "operationId": "ssoEmergencyLogin", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid" }, "bypass_code": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 1 } }, "required": [ "connection_id", "bypass_code", "email", "password" ] } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "number" }, "user_id": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" } }, "required": [ "session_id", "access_token", "refresh_token", "expires_in", "user_id", "email", "email_verified" ] } } } }, "400": { "description": "Invalid bypass code", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "operationId": "createWebhook", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Webhook name (unique per tenant)", "example": "Production Events" }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "HTTPS webhook endpoint URL", "example": "https://api.example.com/webhooks/rakomi" }, "description": { "type": "string", "maxLength": 500, "description": "Optional description" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "user.created", "user.activated", "user.came_of_age", "user.deleted", "auth.login", "auth.password_changed", "webhook.test", "user.updated", "user.blocked", "user.unblocked", "auth.logout", "auth.failed", "token.refreshed", "session.revoked_all", "key.created", "key.revoked", "tenant.updated", "tenant.deleted", "member.invited", "member.removed", "import.completed", "compliance.data_exported", "compliance.dpa_generated", "compliance.dpa_downloaded", "compliance.subprocessor_updated", "compliance.audit_package_generated", "compliance.bundle_generated", "compliance.breach_assessed", "compliance.dpia_generated", "compliance.vendor_packet_generated", "compliance.minor_report_generated", "compliance.dpia_gate_linked", "compliance.share_link_created", "compliance.share_link_accessed", "compliance.events_exported", "webhook.auto_disabled", "webhook.reactivated", "auth_hook.auto_disabled", "auth_hook.reactivated", "marketplace.integration_auto_disabled", "plan.updated", "auth.mfa_enabled", "auth.mfa_disabled", "auth.mfa_challenge_failed", "auth.mfa_recovery_code_used", "tenant.mfa_policy_updated", "auth.mfa_reset_by_admin", "auth.mfa_self_reset", "auth.magic_link_requested", "auth.magic_link_login", "auth.magic_link_scanner_detected", "auth.email_otp_requested", "auth.email_otp_login", "auth.email_otp_exhausted", "auth.email_otp_disabled", "auth.sms_otp_requested", "auth.sms_otp_login", "auth.sms_otp_failed", "auth.sms_otp_exhausted", "auth.sms_otp_disabled", "auth.sms_otp_quota_exhausted", "auth.phone_verify_requested", "auth.phone_verified", "tenant.sms_otp_toggled", "tenant.branding_updated", "session.expired", "session.revoked", "role.created", "role.updated", "role.deleted", "role.force_deleted", "user.role_assigned", "user.role_removed", "user.metadata_updated", "m2m.token_issued", "jwt_claims.template_updated", "feature_flag.created", "feature_flag.updated", "feature_flag.deleted", "subscription.created", "subscription.updated", "subscription.cancelled", "subscription.trial_ending", "payment.failed", "organization.created", "organization.deleted", "organization.member_added", "organization.member_removed", "organization.member_role_changed", "organization.policy_updated", "organization.ownership_transferred", "organization.membership_expiring_soon", "organization.policy_violation", "user.passkey_registered", "user.passkey_deleted", "user.passkey_renamed", "user.claimed", "user.account_linked", "user.account_unlinked", "oauth.token_exchange.issued", "oauth.ciba.token_issued", "oauth_client.scopes_updated", "agent.created", "agent.revoked", "agent.user_revoked", "agent.user_restored", "agent.alert_triggered", "user.consent_receipts_revoked" ] }, "maxItems": 108, "description": "Event types to subscribe to (null = all events)" } }, "required": [ "name", "url" ] } } } }, "responses": { "201": { "description": "Webhook created (signing secret shown once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "signing_secret": { "type": "string" }, "signing_secret_prefix": { "type": "string" }, "status": { "type": "string" }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "circuit_breaker_status": { "type": "string" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "url", "signing_secret", "signing_secret_prefix", "status", "event_types", "circuit_breaker_status", "created_by", "created_at", "updated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit reached or insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Duplicate URL or name", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "SSRF blocked, invalid URL, or invalid event types", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "operationId": "listWebhooks", "parameters": [ { "schema": { "type": "string", "description": "Pagination cursor" }, "required": false, "description": "Pagination cursor", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Results per page", "example": 20 }, "required": false, "description": "Results per page", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paginated list of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "signing_secret_prefix": { "type": "string" }, "status": { "type": "string" }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "circuit_breaker_status": { "type": "string" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "url", "signing_secret_prefix", "status", "event_types", "circuit_breaker_status", "created_by", "created_at", "updated_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook endpoint", "operationId": "getWebhook", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Webhook ID" }, "required": true, "description": "Webhook ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "signing_secret_prefix": { "type": "string" }, "status": { "type": "string" }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "circuit_breaker_status": { "type": "string" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "url", "signing_secret_prefix", "status", "event_types", "circuit_breaker_status", "created_by", "created_at", "updated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "operationId": "updateWebhook", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Webhook ID" }, "required": true, "description": "Webhook ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "description": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "user.created", "user.activated", "user.came_of_age", "user.deleted", "auth.login", "auth.password_changed", "webhook.test", "user.updated", "user.blocked", "user.unblocked", "auth.logout", "auth.failed", "token.refreshed", "session.revoked_all", "key.created", "key.revoked", "tenant.updated", "tenant.deleted", "member.invited", "member.removed", "import.completed", "compliance.data_exported", "compliance.dpa_generated", "compliance.dpa_downloaded", "compliance.subprocessor_updated", "compliance.audit_package_generated", "compliance.bundle_generated", "compliance.breach_assessed", "compliance.dpia_generated", "compliance.vendor_packet_generated", "compliance.minor_report_generated", "compliance.dpia_gate_linked", "compliance.share_link_created", "compliance.share_link_accessed", "compliance.events_exported", "webhook.auto_disabled", "webhook.reactivated", "auth_hook.auto_disabled", "auth_hook.reactivated", "marketplace.integration_auto_disabled", "plan.updated", "auth.mfa_enabled", "auth.mfa_disabled", "auth.mfa_challenge_failed", "auth.mfa_recovery_code_used", "tenant.mfa_policy_updated", "auth.mfa_reset_by_admin", "auth.mfa_self_reset", "auth.magic_link_requested", "auth.magic_link_login", "auth.magic_link_scanner_detected", "auth.email_otp_requested", "auth.email_otp_login", "auth.email_otp_exhausted", "auth.email_otp_disabled", "auth.sms_otp_requested", "auth.sms_otp_login", "auth.sms_otp_failed", "auth.sms_otp_exhausted", "auth.sms_otp_disabled", "auth.sms_otp_quota_exhausted", "auth.phone_verify_requested", "auth.phone_verified", "tenant.sms_otp_toggled", "tenant.branding_updated", "session.expired", "session.revoked", "role.created", "role.updated", "role.deleted", "role.force_deleted", "user.role_assigned", "user.role_removed", "user.metadata_updated", "m2m.token_issued", "jwt_claims.template_updated", "feature_flag.created", "feature_flag.updated", "feature_flag.deleted", "subscription.created", "subscription.updated", "subscription.cancelled", "subscription.trial_ending", "payment.failed", "organization.created", "organization.deleted", "organization.member_added", "organization.member_removed", "organization.member_role_changed", "organization.policy_updated", "organization.ownership_transferred", "organization.membership_expiring_soon", "organization.policy_violation", "user.passkey_registered", "user.passkey_deleted", "user.passkey_renamed", "user.claimed", "user.account_linked", "user.account_unlinked", "oauth.token_exchange.issued", "oauth.ciba.token_issued", "oauth_client.scopes_updated", "agent.created", "agent.revoked", "agent.user_revoked", "agent.user_restored", "agent.alert_triggered", "user.consent_receipts_revoked" ] }, "maxItems": 108 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "signing_secret_prefix": { "type": "string" }, "status": { "type": "string" }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "circuit_breaker_status": { "type": "string" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "url", "signing_secret_prefix", "status", "event_types", "circuit_breaker_status", "created_by", "created_at", "updated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Duplicate URL or name", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "SSRF blocked or invalid URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "operationId": "deleteWebhook", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Webhook ID" }, "required": true, "description": "Webhook ID", "name": "id", "in": "path" } ], "responses": { "204": { "description": "Webhook deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test webhook event", "operationId": "testWebhook", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Webhook ID" }, "required": true, "description": "Webhook ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Test delivery result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "http_status": { "type": [ "number", "null" ] }, "response_time_ms": { "type": "number" }, "failure_reason": { "type": [ "string", "null" ] }, "delivery_id": { "type": "string", "format": "uuid" } }, "required": [ "success", "http_status", "response_time_ms", "failure_reason", "delivery_id" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Webhook is not active", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/webhooks/signing-key/rotate": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate webhook signing key for all webhooks", "operationId": "rotateWebhookSigningKey", "responses": { "200": { "description": "Signing key rotated (new secret shown once)", "headers": { "cache-control": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "signing_secret": { "type": "string", "description": "New signing secret (one-time visibility)" }, "signing_secret_prefix": { "type": "string", "description": "Masked prefix for identification" }, "rotated_at": { "type": "string", "format": "date-time", "description": "Rotation timestamp" } }, "required": [ "signing_secret", "signing_secret_prefix", "rotated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No active webhooks found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Rotation cooldown (24h)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "operationId": "listWebhookDeliveries", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Webhook ID" }, "required": true, "description": "Webhook ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Comma-separated delivery statuses to filter by (valid: pending, processing, delivered, retrying, failed, circuit_open, cancelled_tenant_deleted, cancelled_webhook_deleted, cancelled_url_changed)", "example": "delivered,failed" }, "required": false, "description": "Comma-separated delivery statuses to filter by (valid: pending, processing, delivered, retrying, failed, circuit_open, cancelled_tenant_deleted, cancelled_webhook_deleted, cancelled_url_changed)", "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "user.created", "user.activated", "user.came_of_age", "user.deleted", "auth.login", "auth.password_changed", "webhook.test", "user.updated", "user.blocked", "user.unblocked", "auth.logout", "auth.failed", "token.refreshed", "session.revoked_all", "key.created", "key.revoked", "tenant.updated", "tenant.deleted", "member.invited", "member.removed", "import.completed", "compliance.data_exported", "compliance.dpa_generated", "compliance.dpa_downloaded", "compliance.subprocessor_updated", "compliance.audit_package_generated", "compliance.bundle_generated", "compliance.breach_assessed", "compliance.dpia_generated", "compliance.vendor_packet_generated", "compliance.minor_report_generated", "compliance.dpia_gate_linked", "compliance.share_link_created", "compliance.share_link_accessed", "compliance.events_exported", "webhook.auto_disabled", "webhook.reactivated", "auth_hook.auto_disabled", "auth_hook.reactivated", "marketplace.integration_auto_disabled", "plan.updated", "auth.mfa_enabled", "auth.mfa_disabled", "auth.mfa_challenge_failed", "auth.mfa_recovery_code_used", "tenant.mfa_policy_updated", "auth.mfa_reset_by_admin", "auth.mfa_self_reset", "auth.magic_link_requested", "auth.magic_link_login", "auth.magic_link_scanner_detected", "auth.email_otp_requested", "auth.email_otp_login", "auth.email_otp_exhausted", "auth.email_otp_disabled", "auth.sms_otp_requested", "auth.sms_otp_login", "auth.sms_otp_failed", "auth.sms_otp_exhausted", "auth.sms_otp_disabled", "auth.sms_otp_quota_exhausted", "auth.phone_verify_requested", "auth.phone_verified", "tenant.sms_otp_toggled", "tenant.branding_updated", "session.expired", "session.revoked", "role.created", "role.updated", "role.deleted", "role.force_deleted", "user.role_assigned", "user.role_removed", "user.metadata_updated", "m2m.token_issued", "jwt_claims.template_updated", "feature_flag.created", "feature_flag.updated", "feature_flag.deleted", "subscription.created", "subscription.updated", "subscription.cancelled", "subscription.trial_ending", "payment.failed", "organization.created", "organization.deleted", "organization.member_added", "organization.member_removed", "organization.member_role_changed", "organization.policy_updated", "organization.ownership_transferred", "organization.membership_expiring_soon", "organization.policy_violation", "user.passkey_registered", "user.passkey_deleted", "user.passkey_renamed", "user.claimed", "user.account_linked", "user.account_unlinked", "oauth.token_exchange.issued", "oauth.ciba.token_issued", "oauth_client.scopes_updated", "agent.created", "agent.revoked", "agent.user_revoked", "agent.user_restored", "agent.alert_triggered", "user.consent_receipts_revoked" ], "description": "Filter by event type" }, "required": false, "description": "Filter by event type", "name": "event_type", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Start of date range (inclusive, ISO 8601)" }, "required": false, "description": "Start of date range (inclusive, ISO 8601)", "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "End of date range (exclusive, ISO 8601)" }, "required": false, "description": "End of date range (exclusive, ISO 8601)", "name": "to", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Pagination cursor (record ID, UUID v7)" }, "required": false, "description": "Pagination cursor (record ID, UUID v7)", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Results per page (default: 20, max: 100)", "example": 20 }, "required": false, "description": "Results per page (default: 20, max: 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paginated list of webhook deliveries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "delivery_id": { "type": "string" }, "event_type": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "http_status": { "type": [ "number", "null" ] }, "response_time_ms": { "type": [ "number", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "attempts": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "delivery_id", "event_type", "url", "status", "http_status", "response_time_ms", "failure_reason", "attempts", "created_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/webhooks/{id}/deliveries/{deliveryId}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook delivery detail", "operationId": "getWebhookDelivery", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Webhook ID" }, "required": true, "description": "Webhook ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Delivery ID" }, "required": true, "description": "Delivery ID", "name": "deliveryId", "in": "path" } ], "responses": { "200": { "description": "Webhook delivery detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "delivery_id": { "type": "string" }, "event_type": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "http_status": { "type": [ "number", "null" ] }, "response_time_ms": { "type": [ "number", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "attempts": { "type": "number" }, "created_at": { "type": "string" }, "payload": {}, "last_attempted_at": { "type": [ "string", "null" ] }, "scheduled_at": { "type": "string" }, "updated_at": { "type": "string" }, "curl_command": { "type": "string" } }, "required": [ "id", "delivery_id", "event_type", "url", "status", "http_status", "response_time_ms", "failure_reason", "attempts", "created_at", "last_attempted_at", "scheduled_at", "updated_at", "curl_command" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Delivery not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/dpa": { "get": { "tags": [ "Compliance" ], "summary": "Generate Data Processing Agreement (DPA)", "operationId": "getDpa", "responses": { "200": { "description": "DPA reflecting live system state", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "format": "uuid" }, "tenant_name": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer" }, "content_hash": { "type": "string" }, "processor": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "contact_email": { "type": "string" } }, "required": [ "name", "address", "contact_email" ] }, "clauses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "article": { "type": "string" }, "title_en": { "type": "string" }, "title_pl": { "type": "string" }, "content_en": { "type": "string" }, "content_pl": { "type": "string" } }, "required": [ "id", "article", "title_en", "title_pl", "content_en", "content_pl" ] } }, "sub_processors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "purpose": { "type": "string" }, "data_types": { "type": "array", "items": { "type": "string" } }, "country": { "type": "string" }, "dpa_status": { "type": "string", "enum": [ "active", "pending", "terminated" ] }, "dpa_url": { "type": "string" }, "transfer_mechanism": { "type": "string", "enum": [ "eu_only", "scc", "dpf", "adequacy", "derogation" ] } }, "required": [ "name", "purpose", "data_types", "country", "dpa_status" ] } }, "security_measures": { "type": "array", "items": { "type": "string" } }, "data_types_processed": { "type": "array", "items": { "type": "string" } } }, "required": [ "tenant_id", "tenant_name", "generated_at", "version", "content_hash", "processor", "clauses", "sub_processors", "security_measures", "data_types_processed" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/subprocessors": { "get": { "tags": [ "Compliance" ], "summary": "List current sub-processors", "operationId": "getSubprocessors", "responses": { "200": { "description": "Sub-processor register", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "purpose": { "type": "string" }, "data_types": { "type": "array", "items": { "type": "string" } }, "country": { "type": "string" }, "dpa_status": { "type": "string", "enum": [ "active", "pending", "terminated" ] }, "dpa_url": { "type": "string" }, "transfer_mechanism": { "type": "string", "enum": [ "eu_only", "scc", "dpf", "adequacy", "derogation" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "purpose", "data_types", "country", "dpa_status", "created_at", "updated_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/processing-activities": { "get": { "tags": [ "Compliance" ], "summary": "Get Art. 30 processing activity records", "operationId": "getProcessingActivities", "responses": { "200": { "description": "Processing activity records (Art. 30 GDPR)", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "format": "uuid" }, "generated_at": { "type": "string", "format": "date-time" }, "activities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "purpose": { "type": "string" }, "legal_basis": { "type": "string" }, "data_categories": { "type": "array", "items": { "type": "string" } }, "data_subjects": { "type": "string" }, "retention": { "type": "string" } }, "required": [ "id", "name", "purpose", "legal_basis", "data_categories", "data_subjects", "retention" ] } } }, "required": [ "tenant_id", "generated_at", "activities" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/data-residency": { "get": { "tags": [ "Compliance" ], "summary": "Get data residency information", "operationId": "getDataResidency", "responses": { "200": { "description": "Data residency and infrastructure details", "content": { "application/json": { "schema": { "type": "object", "properties": { "region": { "type": "string" }, "location": { "type": "string" }, "provider": { "type": "string" }, "provider_description": { "type": "string" }, "database": { "type": "object", "properties": { "provider": { "type": "string" }, "location": { "type": "string" }, "encryption_at_rest": { "type": "boolean" } }, "required": [ "provider", "location", "encryption_at_rest" ] }, "email": { "type": "object", "properties": { "provider": { "type": "string" }, "description": { "type": "string" } }, "required": [ "provider", "description" ] }, "backups": { "type": "object", "properties": { "location": { "type": "string" }, "encrypted_at_rest": { "type": "boolean" } }, "required": [ "location", "encrypted_at_rest" ] } }, "required": [ "region", "location", "provider", "provider_description", "database", "email", "backups" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/audit-readiness": { "get": { "tags": [ "Compliance" ], "summary": "Get Audit Readiness Score", "operationId": "getAuditReadiness", "responses": { "200": { "description": "Audit Readiness Score with check breakdown", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=30" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "passed": { "type": "boolean" }, "explanation": { "type": "string" }, "action_url": { "type": "string" }, "last_verified": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "label", "passed", "explanation", "action_url", "last_verified" ] } }, "computed_at": { "type": "string", "format": "date-time" } }, "required": [ "score", "checks", "computed_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/minor-users": { "get": { "tags": [ "Compliance" ], "summary": "Get the Minor Users compliance summary", "operationId": "getMinorUsers", "responses": { "200": { "description": "Minor-account counts + bounded guardian-action audit-log view", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=30" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "minor_account_count": { "type": "integer", "minimum": 0 }, "pending_consent_count": { "type": "integer", "minimum": 0 }, "guardian_actions": { "type": "array", "items": { "type": "object", "properties": { "action_kind": { "type": "string", "enum": [ "view", "export", "withdraw", "delete" ] }, "outcome": { "type": [ "string", "null" ], "enum": [ "success", "denied", "no_op", null ] }, "occurred_at": { "type": "string", "format": "date-time" }, "guardian_records_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "action_kind", "outcome", "occurred_at", "guardian_records_id" ], "additionalProperties": false } } }, "required": [ "minor_account_count", "pending_consent_count", "guardian_actions" ], "additionalProperties": false } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/audit-package": { "post": { "tags": [ "Compliance" ], "summary": "Generate audit package ZIP with all compliance artifacts", "description": "Generates a signed ZIP \"audit emergency kit\" of compliance artifacts rendered as human-readable PDFs, plus machine-readable JSON, a self-describing signed manifest (rakomi-audit-package/1.1.0), and an offline verification kit (VERIFY.md + signing-key.pub.pem + verify.mjs). Tier is resolved SERVER-SIDE from the authenticated tenant's plan: Free receives the BASIC tier (the statutory documents — Data Processing Agreement, Art. 30 Record of Processing Activities, Subprocessor Register — which cannot be paywalled); Pro+ receives the FULL tier (all nine documents). An optional `tier` parameter may only NARROW to basic; requesting `tier=full` without an eligible plan returns 403 compliance/plan_required with an upgrade URL. The delivered tier is echoed in the X-Compliance-Bundle-Tier response header and in manifest.json.tier. The manifest is an integrity self-attestation (RSA-SHA256 detached signature over SHA-256 hex content hashes, verifiable against the published JWKS) — a tamper-evident attestation, not an electronic signature in the legal sense. NOTE: this is compliance-artifact export, NOT GDPR Art. 20 personal-data portability (a different endpoint).", "operationId": "postAuditPackage", "parameters": [ { "schema": { "type": "string", "enum": [ "basic", "full" ], "description": "Optional tier override; may only narrow to basic. Omit to use the plan-derived tier." }, "required": false, "description": "Optional tier override; may only narrow to basic. Omit to use the plan-derived tier.", "name": "tier", "in": "query" } ], "responses": { "200": { "description": "ZIP archive with all compliance artifacts", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Full tier requires a Pro+ plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Package too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "A generation is already in progress for this tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/data-export/{userId}": { "post": { "tags": [ "Compliance" ], "summary": "Export user data as CSV (GDPR Art. 20)", "description": "Returns CSV with columns: email (string), email_verified (boolean), created_at (ISO 8601), last_login_at (ISO 8601), auth_method (string), consent_given_at (ISO 8601), federated_providers (string). Consumers MUST parse by column header name, not positional index.", "operationId": "postDataExport", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "userId", "in": "path" }, { "schema": { "type": "string", "enum": [ "csv" ], "default": "csv" }, "required": false, "name": "format", "in": "query" } ], "responses": { "200": { "description": "CSV file with user data export", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/share-link": { "post": { "tags": [ "Compliance" ], "summary": "Create a shareable compliance link", "operationId": "postShareLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact_type": { "type": "string", "enum": [ "audit_package", "data_export" ], "default": "audit_package" }, "ttl_days": { "type": "integer", "minimum": 1, "maximum": 30, "default": 7 }, "user_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Share link created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "artifact_type": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "artifact_type", "expires_at", "created_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan required or insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/deletion-certificates/{certificateId}": { "get": { "tags": [ "Compliance" ], "summary": "Get a GDPR Art. 17 deletion certificate by ID", "operationId": "getDeletionCertificate", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Deletion certificate ID" }, "required": true, "description": "Deletion certificate ID", "name": "certificateId", "in": "path" } ], "responses": { "200": { "description": "Deletion certificate", "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate_id": { "type": "string", "format": "uuid" }, "entity_type": { "type": "string", "enum": [ "user", "tenant" ] }, "entity_id": { "type": "string", "format": "uuid" }, "deleted_at": { "type": "string", "format": "date-time" }, "deleted_by": { "type": "string" }, "data_types_deleted": { "type": "array", "items": { "type": "string" } }, "data_retained": { "type": "array", "items": { "type": "string" } }, "hash": { "type": "string" } }, "required": [ "certificate_id", "entity_type", "entity_id", "deleted_at", "deleted_by", "data_types_deleted", "data_retained", "hash" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Certificate not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/share-link/{id}": { "delete": { "tags": [ "Compliance" ], "summary": "Revoke a share link", "operationId": "deleteShareLink", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Share link ID" }, "required": true, "description": "Share link ID", "name": "id", "in": "path" } ], "responses": { "204": { "description": "Share link revoked" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Share link not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/breach-assessments": { "post": { "tags": [ "Compliance" ], "summary": "Create a breach assessment (Art. 33 decision support)", "description": "Runs the four-question GDPR Art. 33/34 decision tree SERVER-SIDE (the client answer is never trusted for the outcome), persists an immutable assessment record with a 72-hour notification deadline, seeds the timeline checklist, and emits the compliance.breach_assessed audit event. Decision support, not legal advice; generated artifacts are DRAFT templates to review before submission/sending. The scope export is breach-scope tooling, NOT GDPR Art. 20 personal-data portability. Pro+ plan required.", "operationId": "createBreachAssessment", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "personal_data_involved": { "type": "boolean" }, "risk_to_individuals": { "type": "boolean" }, "high_risk_to_individuals": { "type": "boolean" }, "affected_categories": { "type": "array", "items": { "type": "string", "enum": [ "email", "password_hashes", "ip_addresses", "session_data", "custom_metadata" ] }, "default": [] }, "breach_description": { "type": "string", "maxLength": 2000 }, "affected_user_estimate": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "discovered_at": { "type": "string", "format": "date-time" } }, "required": [ "personal_data_involved", "risk_to_individuals", "high_risk_to_individuals" ] } } } }, "responses": { "201": { "description": "Assessment created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "no_notification", "uodo_required", "uodo_and_subjects_required" ] }, "guidance": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "no_notification", "uodo_required", "uodo_and_subjects_required" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "articles": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "outcome", "title", "summary", "articles", "steps" ] }, "personal_data_involved": { "type": "boolean" }, "risk_to_individuals": { "type": "boolean" }, "high_risk_to_individuals": { "type": "boolean" }, "affected_categories": { "type": "array", "items": { "type": "string", "enum": [ "email", "password_hashes", "ip_addresses", "session_data", "custom_metadata" ] } }, "breach_description": { "type": "string" }, "affected_user_estimate": { "type": "integer" }, "discovered_at": { "type": "string", "format": "date-time" }, "notification_deadline_at": { "type": "string", "format": "date-time" }, "snapshot_at": { "type": "string", "format": "date-time" }, "content_hash": { "type": "string" }, "created_by": { "type": "string" }, "actor_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "string", "enum": [ "discovery", "assessment", "notification", "remediation" ] }, "completed": { "type": "boolean" }, "completed_at": { "type": "string", "format": "date-time" } }, "required": [ "step", "completed" ] } }, "artifacts": { "type": "object", "properties": { "uodo_pdf": { "type": "boolean" }, "subject_letter_pdf": { "type": "boolean" }, "scope_export": { "type": "boolean" } }, "required": [ "uodo_pdf", "subject_letter_pdf", "scope_export" ] } }, "required": [ "id", "outcome", "guidance", "personal_data_involved", "risk_to_individuals", "high_risk_to_individuals", "affected_categories", "discovered_at", "notification_deadline_at", "snapshot_at", "content_hash", "created_by", "actor_type", "created_at", "checklist", "artifacts" ] } } } }, "400": { "description": "Invalid answers (non-monotonic / missing categories)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Compliance" ], "summary": "List breach assessment history (newest-first)", "operationId": "listBreachAssessments", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Assessment history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "no_notification", "uodo_required", "uodo_and_subjects_required" ] }, "guidance": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "no_notification", "uodo_required", "uodo_and_subjects_required" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "articles": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "outcome", "title", "summary", "articles", "steps" ] }, "personal_data_involved": { "type": "boolean" }, "risk_to_individuals": { "type": "boolean" }, "high_risk_to_individuals": { "type": "boolean" }, "affected_categories": { "type": "array", "items": { "type": "string", "enum": [ "email", "password_hashes", "ip_addresses", "session_data", "custom_metadata" ] } }, "breach_description": { "type": "string" }, "affected_user_estimate": { "type": "integer" }, "discovered_at": { "type": "string", "format": "date-time" }, "notification_deadline_at": { "type": "string", "format": "date-time" }, "snapshot_at": { "type": "string", "format": "date-time" }, "content_hash": { "type": "string" }, "created_by": { "type": "string" }, "actor_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "string", "enum": [ "discovery", "assessment", "notification", "remediation" ] }, "completed": { "type": "boolean" }, "completed_at": { "type": "string", "format": "date-time" } }, "required": [ "step", "completed" ] } }, "artifacts": { "type": "object", "properties": { "uodo_pdf": { "type": "boolean" }, "subject_letter_pdf": { "type": "boolean" }, "scope_export": { "type": "boolean" } }, "required": [ "uodo_pdf", "subject_letter_pdf", "scope_export" ] } }, "required": [ "id", "outcome", "guidance", "personal_data_involved", "risk_to_individuals", "high_risk_to_individuals", "affected_categories", "discovered_at", "notification_deadline_at", "snapshot_at", "content_hash", "created_by", "actor_type", "created_at", "checklist", "artifacts" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": "string", "format": "date-time" }, "has_more": { "type": "boolean" } }, "required": [ "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/breach-assessments/{id}/uodo-notification.pdf": { "get": { "tags": [ "Compliance" ], "summary": "Download the pre-filled UODO notification draft PDF", "description": "DRAFT / TEMPLATE — review before submission. Only valid for outcomes requiring UODO notification. Decision support, not legal advice; generated artifacts are DRAFT templates to review before submission/sending. The scope export is breach-scope tooling, NOT GDPR Art. 20 personal-data portability. Pro+ plan required.", "operationId": "downloadBreachUodoPdf", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Breach assessment id" }, "required": true, "description": "Breach assessment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Assessment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Outcome does not require a UODO notification", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/breach-assessments/{id}/subject-letter.pdf": { "get": { "tags": [ "Compliance" ], "summary": "Download the Art. 34 data-subject letter template PDF (HIGH-risk only)", "description": "DRAFT / TEMPLATE — review before sending. Only valid for the HIGH-risk outcome. Decision support, not legal advice; generated artifacts are DRAFT templates to review before submission/sending. The scope export is breach-scope tooling, NOT GDPR Art. 20 personal-data portability. Pro+ plan required.", "operationId": "downloadBreachSubjectPdf", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Breach assessment id" }, "required": true, "description": "Breach assessment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Assessment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Outcome is not HIGH-risk", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/breach-assessments/{id}/scope-export": { "get": { "tags": [ "Compliance" ], "summary": "Download the bounded affected-user scope export (CSV/JSON)", "description": "Bounded, tenant-scoped affected-user list (id, email, created_at, last_login only — no secrets). CSV is formula-injection-safe; overflow is surfaced as an explicit note, never a silent truncation. This is breach-scope tooling, NOT GDPR Art. 20 personal-data portability. Decision support, not legal advice; generated artifacts are DRAFT templates to review before submission/sending. The scope export is breach-scope tooling, NOT GDPR Art. 20 personal-data portability. Pro+ plan required.", "operationId": "downloadBreachScopeExport", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Breach assessment id" }, "required": true, "description": "Breach assessment id", "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "csv", "json" ], "default": "csv" }, "required": false, "name": "format", "in": "query" } ], "responses": { "200": { "description": "Scope export", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Assessment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/breach-assessments/{id}/checklist": { "patch": { "tags": [ "Compliance" ], "summary": "Update a single timeline-checklist step (the only mutable state)", "description": "Toggles one milestone step's completion. Never mutates the assessment answers/outcome/content hash.", "operationId": "updateBreachChecklist", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Breach assessment id" }, "required": true, "description": "Breach assessment id", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "string", "enum": [ "discovery", "assessment", "notification", "remediation" ] }, "completed": { "type": "boolean" } }, "required": [ "step", "completed" ] } } } }, "responses": { "200": { "description": "Updated assessment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "no_notification", "uodo_required", "uodo_and_subjects_required" ] }, "guidance": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "no_notification", "uodo_required", "uodo_and_subjects_required" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "articles": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "outcome", "title", "summary", "articles", "steps" ] }, "personal_data_involved": { "type": "boolean" }, "risk_to_individuals": { "type": "boolean" }, "high_risk_to_individuals": { "type": "boolean" }, "affected_categories": { "type": "array", "items": { "type": "string", "enum": [ "email", "password_hashes", "ip_addresses", "session_data", "custom_metadata" ] } }, "breach_description": { "type": "string" }, "affected_user_estimate": { "type": "integer" }, "discovered_at": { "type": "string", "format": "date-time" }, "notification_deadline_at": { "type": "string", "format": "date-time" }, "snapshot_at": { "type": "string", "format": "date-time" }, "content_hash": { "type": "string" }, "created_by": { "type": "string" }, "actor_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "string", "enum": [ "discovery", "assessment", "notification", "remediation" ] }, "completed": { "type": "boolean" }, "completed_at": { "type": "string", "format": "date-time" } }, "required": [ "step", "completed" ] } }, "artifacts": { "type": "object", "properties": { "uodo_pdf": { "type": "boolean" }, "subject_letter_pdf": { "type": "boolean" }, "scope_export": { "type": "boolean" } }, "required": [ "uodo_pdf", "subject_letter_pdf", "scope_export" ] } }, "required": [ "id", "outcome", "guidance", "personal_data_involved", "risk_to_individuals", "high_risk_to_individuals", "affected_categories", "discovered_at", "notification_deadline_at", "snapshot_at", "content_hash", "created_by", "actor_type", "created_at", "checklist", "artifacts" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Assessment or step not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/breach-assessments/{id}": { "get": { "tags": [ "Compliance" ], "summary": "Get one breach assessment (incl. timeline + checklist)", "operationId": "getBreachAssessment", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Breach assessment id" }, "required": true, "description": "Breach assessment id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Assessment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "no_notification", "uodo_required", "uodo_and_subjects_required" ] }, "guidance": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "no_notification", "uodo_required", "uodo_and_subjects_required" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "articles": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "outcome", "title", "summary", "articles", "steps" ] }, "personal_data_involved": { "type": "boolean" }, "risk_to_individuals": { "type": "boolean" }, "high_risk_to_individuals": { "type": "boolean" }, "affected_categories": { "type": "array", "items": { "type": "string", "enum": [ "email", "password_hashes", "ip_addresses", "session_data", "custom_metadata" ] } }, "breach_description": { "type": "string" }, "affected_user_estimate": { "type": "integer" }, "discovered_at": { "type": "string", "format": "date-time" }, "notification_deadline_at": { "type": "string", "format": "date-time" }, "snapshot_at": { "type": "string", "format": "date-time" }, "content_hash": { "type": "string" }, "created_by": { "type": "string" }, "actor_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "string", "enum": [ "discovery", "assessment", "notification", "remediation" ] }, "completed": { "type": "boolean" }, "completed_at": { "type": "string", "format": "date-time" } }, "required": [ "step", "completed" ] } }, "artifacts": { "type": "object", "properties": { "uodo_pdf": { "type": "boolean" }, "subject_letter_pdf": { "type": "boolean" }, "scope_export": { "type": "boolean" } }, "required": [ "uodo_pdf", "subject_letter_pdf", "scope_export" ] } }, "required": [ "id", "outcome", "guidance", "personal_data_involved", "risk_to_individuals", "high_risk_to_individuals", "affected_categories", "discovered_at", "notification_deadline_at", "snapshot_at", "content_hash", "created_by", "actor_type", "created_at", "checklist", "artifacts" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Assessment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/dpia-assessments": { "post": { "tags": [ "Compliance" ], "summary": "Create a DPIA (Art. 35) — auto-populated, server-scored, version 1", "description": "Auto-populates the processing description (Art. 35(7)(a), incl. the data-flow depiction) and mitigation measures (Art. 35(7)(d)), SEEDS the likelihood × severity matrix from your configuration (you confirm/override), derives the residual risk levels + the Art. 36 prior-consultation advisory SERVER-SIDE, persists an immutable version-1 record, and emits compliance.dpia_generated. Controller accountability artifact (GDPR Art. 35) — compliance support, not legal advice; Rakomi assists the Tenant-as-controller as processor under Art. 28(3)(f) and does not perform or file the assessment. This endpoint serves the controller's Art. 5(2)/Art. 35 accountability — it is NOT a data-subject Art. 15/20 request surface. Pro+ plan required.", "operationId": "createDpiaAssessment", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "description_supplement": { "type": "string", "maxLength": 2000 }, "necessity": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "lawful_basis", "purpose_limitation", "data_minimisation", "storage_limitation", "accuracy", "transparency" ] }, "answer": { "type": "boolean" }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "id", "answer" ], "additionalProperties": false }, "maxItems": 6, "default": [] }, "data_subjects_consulted": { "type": "string", "enum": [ "sought", "not_sought", "not_applicable" ] }, "data_subjects_note": { "type": "string", "maxLength": 2000 }, "codes_of_conduct": { "type": "string", "maxLength": 2000 }, "exemption_note": { "type": "string", "maxLength": 2000 }, "supplement": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, "risks": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "likelihood": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "severity": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "mitigations": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 12, "default": [] }, "seed_source": { "type": "string", "enum": [ "rakomi_derived", "tenant_override" ] } }, "required": [ "category", "likelihood", "severity" ], "additionalProperties": false }, "maxItems": 4 }, "mitigations_supplement": { "type": "string", "maxLength": 2000 }, "dpo": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 2000 }, "consulted_at": { "type": "string", "format": "date" }, "opinion": { "type": "string", "maxLength": 2000 }, "advice_sought": { "type": "boolean" }, "advice_followed": { "type": [ "boolean", "null" ] } }, "additionalProperties": false }, "risk_treatment_outcome": { "type": "string", "enum": [ "accept", "mitigate_then_accept", "consult_authority", "do_not_proceed" ] }, "next_review_at": { "type": "string", "format": "date" }, "snapshot_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "DPIA created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dpia_key": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "is_current": { "type": "boolean" }, "title": { "type": "string" }, "description": { "type": "string" }, "necessity": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "wp248_test": { "type": "string" }, "answer": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "id", "wp248_test", "answer" ] } }, "data_subjects_consulted": { "type": "string", "enum": [ "sought", "not_sought", "not_applicable" ] }, "data_subjects_note": { "type": "string" }, "codes_of_conduct": { "type": "string" }, "exemption_note": { "type": "string" }, "supplement": { "type": "string" } }, "required": [ "answers" ] }, "risks": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "likelihood": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "severity": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "risk_level": { "type": "string", "enum": [ "low", "moderate", "high", "very_high" ] }, "mitigations": { "type": "array", "items": { "type": "string" } }, "seed_source": { "type": "string", "enum": [ "rakomi_derived", "tenant_override" ] } }, "required": [ "category", "likelihood", "severity", "risk_level", "mitigations", "seed_source" ] } }, "mitigations": { "type": "array", "items": { "type": "string" } }, "requires_prior_consultation": { "type": "boolean" }, "risk_treatment_outcome": { "type": "string", "enum": [ "accept", "mitigate_then_accept", "consult_authority", "do_not_proceed" ] }, "dpo": { "type": "object", "properties": { "name": { "type": "string" }, "consulted_at": { "type": "string" }, "opinion": { "type": "string" }, "advice_sought": { "type": "boolean" }, "advice_followed": { "type": [ "boolean", "null" ] } } }, "next_review_at": { "type": "string" }, "review_reminder_sent_at": { "type": "string" }, "methodology_version": { "type": "string" }, "config_stale": { "type": "boolean" }, "content_hash": { "type": "string" }, "created_by": { "type": "string" }, "actor_type": { "type": "string" }, "snapshot_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "dpia_key", "version", "is_current", "description", "necessity", "risks", "mitigations", "requires_prior_consultation", "dpo", "next_review_at", "methodology_version", "config_stale", "content_hash", "created_by", "actor_type", "snapshot_at", "created_at" ] } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Compliance" ], "summary": "List DPIA history (one entry per chain, current head, newest-first)", "description": "Returns the CURRENT head of every DPIA chain. The head-list + per-chain expansion on GET-one is the deletion-evidence framing an auditor expects (\"show me every DPIA you ever authored and prove none were deleted\"). Controller accountability artifact (GDPR Art. 35) — compliance support, not legal advice; Rakomi assists the Tenant-as-controller as processor under Art. 28(3)(f) and does not perform or file the assessment. This endpoint serves the controller's Art. 5(2)/Art. 35 accountability — it is NOT a data-subject Art. 15/20 request surface. Pro+ plan required.", "operationId": "listDpiaAssessments", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "DPIA history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dpia_key": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "is_current": { "type": "boolean" }, "title": { "type": "string" }, "description": { "type": "string" }, "necessity": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "wp248_test": { "type": "string" }, "answer": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "id", "wp248_test", "answer" ] } }, "data_subjects_consulted": { "type": "string", "enum": [ "sought", "not_sought", "not_applicable" ] }, "data_subjects_note": { "type": "string" }, "codes_of_conduct": { "type": "string" }, "exemption_note": { "type": "string" }, "supplement": { "type": "string" } }, "required": [ "answers" ] }, "risks": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "likelihood": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "severity": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "risk_level": { "type": "string", "enum": [ "low", "moderate", "high", "very_high" ] }, "mitigations": { "type": "array", "items": { "type": "string" } }, "seed_source": { "type": "string", "enum": [ "rakomi_derived", "tenant_override" ] } }, "required": [ "category", "likelihood", "severity", "risk_level", "mitigations", "seed_source" ] } }, "mitigations": { "type": "array", "items": { "type": "string" } }, "requires_prior_consultation": { "type": "boolean" }, "risk_treatment_outcome": { "type": "string", "enum": [ "accept", "mitigate_then_accept", "consult_authority", "do_not_proceed" ] }, "dpo": { "type": "object", "properties": { "name": { "type": "string" }, "consulted_at": { "type": "string" }, "opinion": { "type": "string" }, "advice_sought": { "type": "boolean" }, "advice_followed": { "type": [ "boolean", "null" ] } } }, "next_review_at": { "type": "string" }, "review_reminder_sent_at": { "type": "string" }, "methodology_version": { "type": "string" }, "config_stale": { "type": "boolean" }, "content_hash": { "type": "string" }, "created_by": { "type": "string" }, "actor_type": { "type": "string" }, "snapshot_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "dpia_key", "version", "is_current", "description", "necessity", "risks", "mitigations", "requires_prior_consultation", "dpo", "next_review_at", "methodology_version", "config_stale", "content_hash", "created_by", "actor_type", "snapshot_at", "created_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": "string", "format": "date-time" }, "has_more": { "type": "boolean" } }, "required": [ "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/dpia-assessments/{dpia_key}/versions": { "post": { "tags": [ "Compliance" ], "summary": "Create a new version of an existing DPIA (Art. 35(11) review)", "description": "Appends a new immutable version to the chain (prior versions preserved). Inherits the prior answers as the editable starting point, increments the version, and flips the current head atomically. Controller accountability artifact (GDPR Art. 35) — compliance support, not legal advice; Rakomi assists the Tenant-as-controller as processor under Art. 28(3)(f) and does not perform or file the assessment. This endpoint serves the controller's Art. 5(2)/Art. 35 accountability — it is NOT a data-subject Art. 15/20 request surface. Pro+ plan required.", "operationId": "createDpiaVersion", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Stable per-DPIA-chain id" }, "required": true, "description": "Stable per-DPIA-chain id", "name": "dpia_key", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "description_supplement": { "type": "string", "maxLength": 2000 }, "necessity": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "lawful_basis", "purpose_limitation", "data_minimisation", "storage_limitation", "accuracy", "transparency" ] }, "answer": { "type": "boolean" }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "id", "answer" ], "additionalProperties": false }, "maxItems": 6, "default": [] }, "data_subjects_consulted": { "type": "string", "enum": [ "sought", "not_sought", "not_applicable" ] }, "data_subjects_note": { "type": "string", "maxLength": 2000 }, "codes_of_conduct": { "type": "string", "maxLength": 2000 }, "exemption_note": { "type": "string", "maxLength": 2000 }, "supplement": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, "risks": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "likelihood": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "severity": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "mitigations": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 12, "default": [] }, "seed_source": { "type": "string", "enum": [ "rakomi_derived", "tenant_override" ] } }, "required": [ "category", "likelihood", "severity" ], "additionalProperties": false }, "maxItems": 4 }, "mitigations_supplement": { "type": "string", "maxLength": 2000 }, "dpo": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 2000 }, "consulted_at": { "type": "string", "format": "date" }, "opinion": { "type": "string", "maxLength": 2000 }, "advice_sought": { "type": "boolean" }, "advice_followed": { "type": [ "boolean", "null" ] } }, "additionalProperties": false }, "risk_treatment_outcome": { "type": "string", "enum": [ "accept", "mitigate_then_accept", "consult_authority", "do_not_proceed" ] }, "next_review_at": { "type": "string", "format": "date" }, "snapshot_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "New version created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dpia_key": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "is_current": { "type": "boolean" }, "title": { "type": "string" }, "description": { "type": "string" }, "necessity": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "wp248_test": { "type": "string" }, "answer": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "id", "wp248_test", "answer" ] } }, "data_subjects_consulted": { "type": "string", "enum": [ "sought", "not_sought", "not_applicable" ] }, "data_subjects_note": { "type": "string" }, "codes_of_conduct": { "type": "string" }, "exemption_note": { "type": "string" }, "supplement": { "type": "string" } }, "required": [ "answers" ] }, "risks": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "likelihood": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "severity": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "risk_level": { "type": "string", "enum": [ "low", "moderate", "high", "very_high" ] }, "mitigations": { "type": "array", "items": { "type": "string" } }, "seed_source": { "type": "string", "enum": [ "rakomi_derived", "tenant_override" ] } }, "required": [ "category", "likelihood", "severity", "risk_level", "mitigations", "seed_source" ] } }, "mitigations": { "type": "array", "items": { "type": "string" } }, "requires_prior_consultation": { "type": "boolean" }, "risk_treatment_outcome": { "type": "string", "enum": [ "accept", "mitigate_then_accept", "consult_authority", "do_not_proceed" ] }, "dpo": { "type": "object", "properties": { "name": { "type": "string" }, "consulted_at": { "type": "string" }, "opinion": { "type": "string" }, "advice_sought": { "type": "boolean" }, "advice_followed": { "type": [ "boolean", "null" ] } } }, "next_review_at": { "type": "string" }, "review_reminder_sent_at": { "type": "string" }, "methodology_version": { "type": "string" }, "config_stale": { "type": "boolean" }, "content_hash": { "type": "string" }, "created_by": { "type": "string" }, "actor_type": { "type": "string" }, "snapshot_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "dpia_key", "version", "is_current", "description", "necessity", "risks", "mitigations", "requires_prior_consultation", "dpo", "next_review_at", "methodology_version", "config_stale", "content_hash", "created_by", "actor_type", "snapshot_at", "created_at" ] } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "DPIA not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Concurrent revision conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/dpia-assessments/{dpia_key}/versions/{version}/pdf": { "get": { "tags": [ "Compliance" ], "summary": "Download a specific DPIA version's report PDF (Art. 29 WP / ISO 29134)", "description": "Downloads the frozen, byte-stable report PDF for the named version (an auditor downloading v1 a year after v2 exists gets v1's content). Controller accountability artifact (GDPR Art. 35) — compliance support, not legal advice; Rakomi assists the Tenant-as-controller as processor under Art. 28(3)(f) and does not perform or file the assessment. This endpoint serves the controller's Art. 5(2)/Art. 35 accountability — it is NOT a data-subject Art. 15/20 request surface. Pro+ plan required.", "operationId": "downloadDpiaPdf", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Stable per-DPIA-chain id" }, "required": true, "description": "Stable per-DPIA-chain id", "name": "dpia_key", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "description": "DPIA version number" }, "required": true, "description": "DPIA version number", "name": "version", "in": "path" } ], "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "DPIA not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/dpia-assessments/{dpia_key}/diff": { "get": { "tags": [ "Compliance" ], "summary": "Diff two versions of a DPIA (Art. 35(11) review aid) — section changes + residual-risk trend", "description": "Read-only, idempotent (RFC 9110 §9.2.1 safe-GET — zero writes, no audit event) structured diff between two immutable versions of ONE DPIA chain: per-Art.-35-section change records (status enum added/removed/modified/unchanged + before/after values) + a residual-risk TREND (per-category direction up/down/unchanged with a signed ordinal level_delta magnitude, reading each version's already-server-scored risk_level — NEVER re-scored) + the Art. 36 prior-consultation delta. Prior art: a structured (typed, not PDF-byte) diff like a GitHub \"Files changed\"; point-in-time comparison of two immutable snapshots; a signed-delta risk-register trend; the ?from=&to= two-anchor compare shape of MediaWiki/GitLab/Confluence revision-compare (orientation reflects request order — from > to is valid). Each version's stored content_hash + snapshot_at are echoed byte-for-byte (Art. 5(2) evidentiary binding, never recomputed). This is an RLS-scoped CONTROLLER-ACCOUNTABILITY read (Art. 5(2)/35(11)) — NOT a data-subject Art. 15/20 access/portability surface. Composes 26.3 getDpiaAssessmentRow (two indexed reads, O(1) in chain length); a 26.3 change to risk_level/requires_prior_consultation is a breaking change here (seam-pinned by tests). Caching: the diff over two immutable rows is perfectly cacheable (strong validator ETag = sha256(from.content_hash || to.content_hash), Cache-Control: private, immutable) — deliberately NOT shipped in this cut (no measured pressure; a labelled door). Error envelope is the project AppError, intentionally NOT RFC 7807 problem+json (consistency with the compliance route family). Controller accountability artifact (GDPR Art. 35) — compliance support, not legal advice; Rakomi assists the Tenant-as-controller as processor under Art. 28(3)(f) and does not perform or file the assessment. This endpoint serves the controller's Art. 5(2)/Art. 35 accountability — it is NOT a data-subject Art. 15/20 request surface. Pro+ plan required.", "operationId": "diffDpiaAssessmentVersions", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Stable per-DPIA-chain id" }, "required": true, "description": "Stable per-DPIA-chain id", "name": "dpia_key", "in": "path" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Source version (orientation preserved; from > to is valid)" }, "required": true, "description": "Source version (orientation preserved; from > to is valid)", "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Target version (orientation preserved; from > to is valid)" }, "required": true, "description": "Target version (orientation preserved; from > to is valid)", "name": "to", "in": "query" } ], "responses": { "200": { "description": "Version diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "dpia_key": { "type": "string", "format": "uuid" }, "from_version": { "type": "integer" }, "to_version": { "type": "integer" }, "from_snapshot_at": { "type": "string" }, "to_snapshot_at": { "type": "string" }, "from_content_hash": { "type": "string" }, "to_content_hash": { "type": "string" }, "content_identical": { "type": "boolean" }, "from_methodology_version": { "type": "string" }, "to_methodology_version": { "type": "string" }, "methodology_changed": { "type": "boolean" }, "has_changes": { "type": "boolean" }, "sections": { "type": "object", "properties": { "description": { "type": "object", "properties": { "changed": { "type": "boolean" }, "text": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] } }, "required": [ "changed", "text" ] }, "necessity": { "type": "object", "properties": { "changed": { "type": "boolean" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "answer_changed": { "type": "boolean" }, "note_changed": { "type": "boolean" }, "from_answer": { "type": "boolean" }, "to_answer": { "type": "boolean" }, "from_note": { "type": "string" }, "to_note": { "type": "string" } }, "required": [ "id", "answer_changed", "note_changed" ] } }, "data_subjects_consulted": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "data_subjects_note": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "codes_of_conduct": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "exemption_note": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "supplement": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] } }, "required": [ "changed", "questions", "data_subjects_consulted", "data_subjects_note", "codes_of_conduct", "exemption_note", "supplement" ] }, "risks": { "type": "object", "properties": { "changed": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "changed": { "type": "boolean" }, "likelihood": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "severity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "risk_level": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "mitigations_added": { "type": "array", "items": { "type": "string" } }, "mitigations_removed": { "type": "array", "items": { "type": "string" } }, "seed_source": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] } }, "required": [ "category", "changed", "likelihood", "severity", "risk_level", "mitigations_added", "mitigations_removed", "seed_source" ] } } }, "required": [ "changed", "categories" ] }, "mitigations": { "type": "object", "properties": { "changed": { "type": "boolean" }, "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } } }, "required": [ "changed", "added", "removed" ] }, "dpo": { "type": "object", "properties": { "changed": { "type": "boolean" }, "name": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "consulted_at": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "opinion": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "advice_sought": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "boolean" }, "to": { "type": "boolean" } }, "required": [ "status" ] }, "advice_followed": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "boolean" }, "to": { "type": "boolean" } }, "required": [ "status" ] } }, "required": [ "changed", "name", "consulted_at", "opinion", "advice_sought", "advice_followed" ] }, "review_schedule": { "type": "object", "properties": { "changed": { "type": "boolean" }, "next_review_at": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] }, "risk_treatment_outcome": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "added", "removed", "modified", "unchanged" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status" ] } }, "required": [ "changed", "next_review_at", "risk_treatment_outcome" ] } }, "required": [ "description", "necessity", "risks", "mitigations", "dpo", "review_schedule" ] }, "risk_trend": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "from_level": { "type": "string" }, "to_level": { "type": "string" }, "direction": { "type": "string", "enum": [ "up", "down", "unchanged" ] }, "level_delta": { "type": "integer" }, "persists_at_or_above_high": { "type": "boolean" } }, "required": [ "category", "from_level", "to_level", "direction", "level_delta", "persists_at_or_above_high" ] } }, "art36": { "type": "object", "properties": { "from": { "type": "boolean" }, "to": { "type": "boolean" }, "change": { "type": "string", "enum": [ "added", "removed", "unchanged" ] } }, "required": [ "from", "to", "change" ] }, "overall_risk_direction": { "type": "string", "enum": [ "up", "down", "unchanged" ] }, "any_persisting_high_risk": { "type": "boolean" }, "review_summary": { "type": "string" } }, "required": [ "dpia_key", "from_version", "to_version", "from_snapshot_at", "to_snapshot_at", "from_content_hash", "to_content_hash", "content_identical", "from_methodology_version", "to_methodology_version", "methodology_changed", "has_changes", "sections", "risk_trend", "art36", "overall_risk_direction", "any_persisting_high_risk" ] } } } }, "400": { "description": "Invalid from/to (non-canonical, out of range, or equal)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "DPIA or version not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/dpia-assessments/drafts": { "put": { "tags": [ "Compliance" ], "summary": "Save / autosave the tenant's single active DPIA wizard draft (mutable scratch)", "description": "Idempotent upsert (PUT) of the tenant's single active draft for the resolved target. Optimistic concurrency via the body `expected_revision` (a deliberate, documented deviation from RFC 7232 If-Match/ETag/412 — internal first-party surface; the 409 body carries the current revision). Omit `expected_revision` on the FIRST save after a fresh open (→ revision 1); include it thereafter. MUTABLE wizard scratch state — NOT an Art. 35 accountability artifact (only the final create/version POST is). Persists the in-progress DPIA wizard body so a long Art. 35 assessment survives a closed tab / refresh / device switch. The draft is stored verbatim, unscored, unhashed; it is NEVER rendered to a PDF, written to the audit log, or dispatched to a webhook — no audit event is emitted, a deliberate data-minimisation decision (not a logging gap). At most one active draft per target: a fresh-DPIA draft (no dpia_key) OR one per chain being revised (dpia_key). Controller accountability artifact (GDPR Art. 35) — compliance support, not legal advice; Rakomi assists the Tenant-as-controller as processor under Art. 28(3)(f) and does not perform or file the assessment. This endpoint serves the controller's Art. 5(2)/Art. 35 accountability — it is NOT a data-subject Art. 15/20 request surface. Pro+ plan required.", "operationId": "upsertDpiaDraft", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "dpia_key_target": { "type": "string", "format": "uuid" }, "wizard_step": { "type": "integer", "minimum": 1, "maximum": 6 }, "body": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "description_supplement": { "type": "string", "maxLength": 2000 }, "necessity": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "lawful_basis", "purpose_limitation", "data_minimisation", "storage_limitation", "accuracy", "transparency" ] }, "answer": { "type": "boolean" }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "id", "answer" ], "additionalProperties": false }, "maxItems": 6, "default": [] }, "data_subjects_consulted": { "type": "string", "enum": [ "sought", "not_sought", "not_applicable" ] }, "data_subjects_note": { "type": "string", "maxLength": 2000 }, "codes_of_conduct": { "type": "string", "maxLength": 2000 }, "exemption_note": { "type": "string", "maxLength": 2000 }, "supplement": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, "risks": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "likelihood": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "severity": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "mitigations": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 12, "default": [] }, "seed_source": { "type": "string", "enum": [ "rakomi_derived", "tenant_override" ] } }, "required": [ "category", "likelihood", "severity" ], "additionalProperties": false }, "maxItems": 4 }, "mitigations_supplement": { "type": "string", "maxLength": 2000 }, "dpo": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 2000 }, "consulted_at": { "type": "string", "format": "date" }, "opinion": { "type": "string", "maxLength": 2000 }, "advice_sought": { "type": "boolean" }, "advice_followed": { "type": [ "boolean", "null" ] } }, "additionalProperties": false }, "risk_treatment_outcome": { "type": "string", "enum": [ "accept", "mitigate_then_accept", "consult_authority", "do_not_proceed" ] }, "next_review_at": { "type": "string", "format": "date" } }, "additionalProperties": false }, "expected_revision": { "type": "integer", "minimum": 1 } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Draft saved (the persisted draft; revision disambiguates create vs update)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dpia_key_target": { "type": "string", "format": "uuid" }, "draft_kind": { "type": "string", "enum": [ "fresh", "revision" ] }, "wizard_step": { "type": "integer" }, "revision": { "type": "integer" }, "body": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "description_supplement": { "type": "string", "maxLength": 2000 }, "necessity": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "lawful_basis", "purpose_limitation", "data_minimisation", "storage_limitation", "accuracy", "transparency" ] }, "answer": { "type": "boolean" }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "id", "answer" ], "additionalProperties": false }, "maxItems": 6, "default": [] }, "data_subjects_consulted": { "type": "string", "enum": [ "sought", "not_sought", "not_applicable" ] }, "data_subjects_note": { "type": "string", "maxLength": 2000 }, "codes_of_conduct": { "type": "string", "maxLength": 2000 }, "exemption_note": { "type": "string", "maxLength": 2000 }, "supplement": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, "risks": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "likelihood": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "severity": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "mitigations": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 12, "default": [] }, "seed_source": { "type": "string", "enum": [ "rakomi_derived", "tenant_override" ] } }, "required": [ "category", "likelihood", "severity" ], "additionalProperties": false }, "maxItems": 4 }, "mitigations_supplement": { "type": "string", "maxLength": 2000 }, "dpo": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 2000 }, "consulted_at": { "type": "string", "format": "date" }, "opinion": { "type": "string", "maxLength": 2000 }, "advice_sought": { "type": "boolean" }, "advice_followed": { "type": [ "boolean", "null" ] } }, "additionalProperties": false }, "risk_treatment_outcome": { "type": "string", "enum": [ "accept", "mitigate_then_accept", "consult_authority", "do_not_proceed" ] }, "next_review_at": { "type": "string", "format": "date" } }, "additionalProperties": false }, "body_schema_version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "draft_kind", "revision", "body", "body_schema_version", "updated_at", "created_at" ] } } } }, "400": { "description": "Invalid body (forged/unknown key, .strict)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Stale revision — the draft was updated elsewhere (body: current revision + updated_at + actor_type)", "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "actor_type": { "type": "string" } }, "required": [ "revision", "updated_at", "actor_type" ] } } } }, "413": { "description": "Draft body exceeds the maximum size", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Compliance" ], "summary": "Resume the tenant's single active DPIA wizard draft (or {draft:null})", "description": "Returns the active draft for the resolved target (omit `dpia_key` → the fresh-DPIA draft; supply it → the draft pinned to revising that chain) so the wizard rehydrates exactly. Returns `{ draft: null }` (200) when none exists. A cross-tenant `dpia_key` is invisible under RLS — indistinguishable from \"no draft\" (never 403). MUTABLE wizard scratch state — NOT an Art. 35 accountability artifact (only the final create/version POST is). Persists the in-progress DPIA wizard body so a long Art. 35 assessment survives a closed tab / refresh / device switch. The draft is stored verbatim, unscored, unhashed; it is NEVER rendered to a PDF, written to the audit log, or dispatched to a webhook — no audit event is emitted, a deliberate data-minimisation decision (not a logging gap). At most one active draft per target: a fresh-DPIA draft (no dpia_key) OR one per chain being revised (dpia_key). Controller accountability artifact (GDPR Art. 35) — compliance support, not legal advice; Rakomi assists the Tenant-as-controller as processor under Art. 28(3)(f) and does not perform or file the assessment. This endpoint serves the controller's Art. 5(2)/Art. 35 accountability — it is NOT a data-subject Art. 15/20 request surface. Pro+ plan required.", "operationId": "getDpiaDraft", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Revise this existing DPIA chain (omit → the fresh-DPIA draft)" }, "required": false, "description": "Revise this existing DPIA chain (omit → the fresh-DPIA draft)", "name": "dpia_key", "in": "query" } ], "responses": { "200": { "description": "The active draft, or { draft: null }", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "dpia_key_target": { "type": "string", "format": "uuid" }, "draft_kind": { "type": "string", "enum": [ "fresh", "revision" ] }, "wizard_step": { "type": "integer" }, "revision": { "type": "integer" }, "body": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "description_supplement": { "type": "string", "maxLength": 2000 }, "necessity": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "lawful_basis", "purpose_limitation", "data_minimisation", "storage_limitation", "accuracy", "transparency" ] }, "answer": { "type": "boolean" }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "id", "answer" ], "additionalProperties": false }, "maxItems": 6, "default": [] }, "data_subjects_consulted": { "type": "string", "enum": [ "sought", "not_sought", "not_applicable" ] }, "data_subjects_note": { "type": "string", "maxLength": 2000 }, "codes_of_conduct": { "type": "string", "maxLength": 2000 }, "exemption_note": { "type": "string", "maxLength": 2000 }, "supplement": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, "risks": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "likelihood": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "severity": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "mitigations": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 12, "default": [] }, "seed_source": { "type": "string", "enum": [ "rakomi_derived", "tenant_override" ] } }, "required": [ "category", "likelihood", "severity" ], "additionalProperties": false }, "maxItems": 4 }, "mitigations_supplement": { "type": "string", "maxLength": 2000 }, "dpo": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 2000 }, "consulted_at": { "type": "string", "format": "date" }, "opinion": { "type": "string", "maxLength": 2000 }, "advice_sought": { "type": "boolean" }, "advice_followed": { "type": [ "boolean", "null" ] } }, "additionalProperties": false }, "risk_treatment_outcome": { "type": "string", "enum": [ "accept", "mitigate_then_accept", "consult_authority", "do_not_proceed" ] }, "next_review_at": { "type": "string", "format": "date" } }, "additionalProperties": false }, "body_schema_version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "draft_kind", "revision", "body", "body_schema_version", "updated_at", "created_at" ] } }, "required": [ "draft" ] } } } }, "400": { "description": "Malformed dpia_key (not a uuid)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Compliance" ], "summary": "Discard the tenant's single active DPIA wizard draft (hard delete, idempotent)", "description": "Hard-deletes the active draft for the resolved target (scratch — a hard delete, not a tombstone, is correct and GDPR-erasure-friendly). Idempotent: 204 even when no draft exists (a \"make it not exist\" intent; a 404 would leak existence). DELETE is intentionally NOT plan-gated so a downgraded (Pro→Free) tenant can always clean up its own scratch state. MUTABLE wizard scratch state — NOT an Art. 35 accountability artifact (only the final create/version POST is). Persists the in-progress DPIA wizard body so a long Art. 35 assessment survives a closed tab / refresh / device switch. The draft is stored verbatim, unscored, unhashed; it is NEVER rendered to a PDF, written to the audit log, or dispatched to a webhook — no audit event is emitted, a deliberate data-minimisation decision (not a logging gap). At most one active draft per target: a fresh-DPIA draft (no dpia_key) OR one per chain being revised (dpia_key). Controller accountability artifact (GDPR Art. 35) — compliance support, not legal advice; Rakomi assists the Tenant-as-controller as processor under Art. 28(3)(f) and does not perform or file the assessment. This endpoint serves the controller's Art. 5(2)/Art. 35 accountability — it is NOT a data-subject Art. 15/20 request surface. Pro+ plan required.", "operationId": "deleteDpiaDraft", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Revise this existing DPIA chain (omit → the fresh-DPIA draft)" }, "required": false, "description": "Revise this existing DPIA chain (omit → the fresh-DPIA draft)", "name": "dpia_key", "in": "query" } ], "responses": { "204": { "description": "Draft discarded (or already absent)" }, "400": { "description": "Malformed dpia_key (not a uuid)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/dpia-assessments/{dpia_key}": { "get": { "tags": [ "Compliance" ], "summary": "Get one DPIA (current head + full version chain + config-stale signal)", "operationId": "getDpiaAssessment", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Stable per-DPIA-chain id" }, "required": true, "description": "Stable per-DPIA-chain id", "name": "dpia_key", "in": "path" } ], "responses": { "200": { "description": "DPIA", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dpia_key": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "is_current": { "type": "boolean" }, "title": { "type": "string" }, "description": { "type": "string" }, "necessity": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "wp248_test": { "type": "string" }, "answer": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "id", "wp248_test", "answer" ] } }, "data_subjects_consulted": { "type": "string", "enum": [ "sought", "not_sought", "not_applicable" ] }, "data_subjects_note": { "type": "string" }, "codes_of_conduct": { "type": "string" }, "exemption_note": { "type": "string" }, "supplement": { "type": "string" } }, "required": [ "answers" ] }, "risks": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "unauthorized_access", "data_loss", "cross_border_transfer", "re_identification" ] }, "likelihood": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "severity": { "type": "string", "enum": [ "negligible", "limited", "significant", "maximum" ] }, "risk_level": { "type": "string", "enum": [ "low", "moderate", "high", "very_high" ] }, "mitigations": { "type": "array", "items": { "type": "string" } }, "seed_source": { "type": "string", "enum": [ "rakomi_derived", "tenant_override" ] } }, "required": [ "category", "likelihood", "severity", "risk_level", "mitigations", "seed_source" ] } }, "mitigations": { "type": "array", "items": { "type": "string" } }, "requires_prior_consultation": { "type": "boolean" }, "risk_treatment_outcome": { "type": "string", "enum": [ "accept", "mitigate_then_accept", "consult_authority", "do_not_proceed" ] }, "dpo": { "type": "object", "properties": { "name": { "type": "string" }, "consulted_at": { "type": "string" }, "opinion": { "type": "string" }, "advice_sought": { "type": "boolean" }, "advice_followed": { "type": [ "boolean", "null" ] } } }, "next_review_at": { "type": "string" }, "review_reminder_sent_at": { "type": "string" }, "methodology_version": { "type": "string" }, "config_stale": { "type": "boolean" }, "content_hash": { "type": "string" }, "created_by": { "type": "string" }, "actor_type": { "type": "string" }, "snapshot_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "version_chain": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "is_current": { "type": "boolean" }, "content_hash": { "type": "string" }, "snapshot_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "actor_type": { "type": "string" } }, "required": [ "id", "version", "is_current", "content_hash", "snapshot_at", "created_by", "actor_type" ] } } }, "required": [ "id", "dpia_key", "version", "is_current", "description", "necessity", "risks", "mitigations", "requires_prior_consultation", "dpo", "next_review_at", "methodology_version", "config_stale", "content_hash", "created_by", "actor_type", "snapshot_at", "created_at", "version_chain" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Pro+ plan required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "DPIA not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/vendor-packet": { "post": { "tags": [ "Compliance" ], "summary": "Generate a signed, versioned vendor compliance packet", "description": "Generates an immutable, version-chained vendor compliance packet for the authenticated tenant and returns its metadata + signature (download the signed ZIP via GET /{id}/download). Officer selections are booleans over canonical sub-processor ids only — a non-canonical id returns 400; an identical resolved selection returns the existing latest version (no-op-if-unchanged). Vendor compliance packet (GDPR Art. 28 processor obligations + Art. 30(2) processor record), scoped to the sub-processors this tenant relies on. Rakomi acts as processor/sub-processor to the Tenant-as-controller — this is NOT the Tenant's own Art. 30(1) controller record, and it is compliance support, not legal advice.", "operationId": "generateVendorPacket", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "selections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "applies": { "type": "boolean" } }, "required": [ "id", "applies" ], "additionalProperties": false }, "maxItems": 64 }, "register_complete": { "type": "boolean" }, "source_data_reviewed_at": { "type": "string", "format": "date-time" }, "snapshot_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Vendor packet generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "supersedes_id": { "type": "string", "format": "uuid" }, "prev_hash": { "type": "string" }, "selected": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "purpose": { "type": "string" }, "data_types": { "type": "array", "items": { "type": "string" } }, "country": { "type": "string" }, "dpa_status": { "type": "string", "enum": [ "active", "pending", "terminated", "unverified" ] }, "dpa_url": { "type": "string" }, "transfer_mechanism": { "type": "string" }, "transfer_basis": { "type": "string" }, "applies": { "type": "boolean" }, "source": { "type": "string", "enum": [ "default", "officer-added", "officer-removed" ] } }, "required": [ "id", "name", "purpose", "data_types", "country", "dpa_status", "transfer_basis", "applies", "source" ] } }, "selected_count": { "type": "integer" }, "document_count": { "type": "integer" }, "snapshot_schema_version": { "type": "string" }, "source_revision": { "type": "string" }, "source_data_reviewed_at": { "type": "string", "format": "date-time" }, "register_complete": { "type": "boolean" }, "generated_for_controller": { "type": "object", "properties": { "tenant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "tenant_id", "name" ] }, "signing_key_id": { "type": "string" }, "bundle_hash": { "type": "string" }, "signature": { "type": "string" }, "generated_by": { "type": "string" }, "actor_type": { "type": "string" }, "snapshot_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "diff": { "type": "object", "properties": { "prior_version": { "type": "integer" }, "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } }, "dpa_status_changes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "name", "from", "to" ] } } }, "required": [ "prior_version", "added", "removed", "dpa_status_changes" ] } }, "required": [ "id", "version", "selected", "selected_count", "document_count", "snapshot_schema_version", "source_revision", "register_complete", "generated_for_controller", "signing_key_id", "bundle_hash", "signature", "generated_by", "actor_type", "snapshot_at", "created_at" ] } } } }, "400": { "description": "Invalid body / non-canonical selection", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "A generation is already in progress for this tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "504": { "description": "Generation timed out", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Compliance" ], "summary": "List vendor packet history (newest-first, version lineage)", "operationId": "listVendorPackets", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Vendor packet history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "supersedes_id": { "type": "string", "format": "uuid" }, "prev_hash": { "type": "string" }, "selected": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "purpose": { "type": "string" }, "data_types": { "type": "array", "items": { "type": "string" } }, "country": { "type": "string" }, "dpa_status": { "type": "string", "enum": [ "active", "pending", "terminated", "unverified" ] }, "dpa_url": { "type": "string" }, "transfer_mechanism": { "type": "string" }, "transfer_basis": { "type": "string" }, "applies": { "type": "boolean" }, "source": { "type": "string", "enum": [ "default", "officer-added", "officer-removed" ] } }, "required": [ "id", "name", "purpose", "data_types", "country", "dpa_status", "transfer_basis", "applies", "source" ] } }, "selected_count": { "type": "integer" }, "document_count": { "type": "integer" }, "snapshot_schema_version": { "type": "string" }, "source_revision": { "type": "string" }, "source_data_reviewed_at": { "type": "string", "format": "date-time" }, "register_complete": { "type": "boolean" }, "generated_for_controller": { "type": "object", "properties": { "tenant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "tenant_id", "name" ] }, "signing_key_id": { "type": "string" }, "bundle_hash": { "type": "string" }, "signature": { "type": "string" }, "generated_by": { "type": "string" }, "actor_type": { "type": "string" }, "snapshot_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "diff": { "type": "object", "properties": { "prior_version": { "type": "integer" }, "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } }, "dpa_status_changes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "name", "from", "to" ] } } }, "required": [ "prior_version", "added", "removed", "dpa_status_changes" ] } }, "required": [ "id", "version", "selected", "selected_count", "document_count", "snapshot_schema_version", "source_revision", "register_complete", "generated_for_controller", "signing_key_id", "bundle_hash", "signature", "generated_by", "actor_type", "snapshot_at", "created_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": "string", "format": "date-time" }, "has_more": { "type": "boolean" } }, "required": [ "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/vendor-packet/defaults": { "get": { "tags": [ "Compliance" ], "summary": "Server-computed default sub-processor selection + freshness/role metadata", "operationId": "getVendorPacketDefaults", "responses": { "200": { "description": "Default selection + metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "purpose": { "type": "string" }, "data_types": { "type": "array", "items": { "type": "string" } }, "country": { "type": "string" }, "dpa_status": { "type": "string", "enum": [ "active", "pending", "terminated", "unverified" ] }, "dpa_url": { "type": "string" }, "transfer_mechanism": { "type": "string" }, "transfer_basis": { "type": "string" }, "applies": { "type": "boolean" }, "source": { "type": "string", "enum": [ "default", "officer-added", "officer-removed" ] } }, "required": [ "id", "name", "purpose", "data_types", "country", "dpa_status", "transfer_basis", "applies", "source" ] } }, "role_framing": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "source_data_reviewed_at": { "type": "string", "format": "date-time" }, "staleness_days": { "type": "integer" }, "register_complete": { "type": "boolean" }, "completeness_disclaimer": { "type": "string" }, "snapshot_schema_version": { "type": "string" }, "latest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "selection_changed": { "type": "boolean" } }, "required": [ "id", "version", "created_at", "selection_changed" ] } }, "required": [ "candidates", "role_framing", "as_of", "register_complete", "completeness_disclaimer", "snapshot_schema_version" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/vendor-packet/{id}/download": { "get": { "tags": [ "Compliance" ], "summary": "Download the signed, offline-verifiable vendor packet ZIP", "operationId": "downloadVendorPacket", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Vendor packet id" }, "required": true, "description": "Vendor packet id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Signed ZIP", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Vendor packet not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/vendor-packet/{id}": { "get": { "tags": [ "Compliance" ], "summary": "Get one vendor packet (metadata + selection + diff)", "operationId": "getVendorPacket", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Vendor packet id" }, "required": true, "description": "Vendor packet id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Vendor packet", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "supersedes_id": { "type": "string", "format": "uuid" }, "prev_hash": { "type": "string" }, "selected": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "purpose": { "type": "string" }, "data_types": { "type": "array", "items": { "type": "string" } }, "country": { "type": "string" }, "dpa_status": { "type": "string", "enum": [ "active", "pending", "terminated", "unverified" ] }, "dpa_url": { "type": "string" }, "transfer_mechanism": { "type": "string" }, "transfer_basis": { "type": "string" }, "applies": { "type": "boolean" }, "source": { "type": "string", "enum": [ "default", "officer-added", "officer-removed" ] } }, "required": [ "id", "name", "purpose", "data_types", "country", "dpa_status", "transfer_basis", "applies", "source" ] } }, "selected_count": { "type": "integer" }, "document_count": { "type": "integer" }, "snapshot_schema_version": { "type": "string" }, "source_revision": { "type": "string" }, "source_data_reviewed_at": { "type": "string", "format": "date-time" }, "register_complete": { "type": "boolean" }, "generated_for_controller": { "type": "object", "properties": { "tenant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "tenant_id", "name" ] }, "signing_key_id": { "type": "string" }, "bundle_hash": { "type": "string" }, "signature": { "type": "string" }, "generated_by": { "type": "string" }, "actor_type": { "type": "string" }, "snapshot_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "diff": { "type": "object", "properties": { "prior_version": { "type": "integer" }, "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } }, "dpa_status_changes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "name", "from", "to" ] } } }, "required": [ "prior_version", "added", "removed", "dpa_status_changes" ] } }, "required": [ "id", "version", "selected", "selected_count", "document_count", "snapshot_schema_version", "source_revision", "register_complete", "generated_for_controller", "signing_key_id", "bundle_hash", "signature", "generated_by", "actor_type", "snapshot_at", "created_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Vendor packet not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/compliance/shared/{token}": { "get": { "tags": [ "Compliance" ], "summary": "Access shared compliance artifacts (public)", "operationId": "getShared", "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "Share link token" }, "required": true, "description": "Share link token", "name": "token", "in": "path" } ], "responses": { "200": { "description": "Shared compliance artifacts", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=3600" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_name": { "type": "string" }, "artifact_type": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "artifacts": { "type": "object", "additionalProperties": {} }, "verification_note": { "type": "string" }, "privacy_notice": { "type": "string" } }, "required": [ "tenant_name", "generated_at", "expires_at", "artifacts", "verification_note", "privacy_notice" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/events": { "get": { "tags": [ "Events" ], "summary": "List audit events with keyset pagination", "description": "Returns audit events for the tenant. Requires date range (max 31 days). Supports filters by user_id, event_type, and result.", "operationId": "listEvents", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "required": true, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": true, "name": "to", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "user_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "tenant.billing_archived", "user.created", "user.deleted", "user.blocked", "user.unblocked", "user.updated", "user.came_of_age", "auth.login", "auth.failed", "auth.password_changed", "compliance.data_exported", "compliance.events_exported", "compliance.deletion_certificate", "compliance.parental_consent_obtained", "compliance.guardian_action", "tenant.deleted", "user.import", "user.import_preview", "import.welcome_emails_queued", "trial.expired", "trial.day0_email", "trial.day3_email", "trial.day7_email", "trial.day11_email", "trial.day15_email", "mau.alert_95", "payment.failed", "payment.authentication_required", "payment.dispute_created", "payment.dispute_closed", "subscription.past_due", "subscription.recovered", "subscription.cancelled", "plan.change_initiated", "billing.withdrawal_waiver", "invoice.paid", "billing.upgrade_survey", "billing.survey_response", "billing.renewal_reminder", "auth.magic_link_requested", "auth.magic_link_login", "auth.magic_link_scanner_detected", "auth.magic_link_ip_mismatch", "auth.email_auto_verified", "auth.email_otp_requested", "auth.email_otp_login", "auth.email_otp_failed", "auth.email_otp_exhausted", "auth.email_otp_disabled", "tenant.settings_updated", "oauth.token_issued", "oauth.token_refreshed", "oauth.code_issued", "oauth.consent_granted", "oauth.token_revoked", "oauth_client.scopes_updated", "oauth_consent.scope_change_declined", "oauth.consent.agent_scope_decision", "oauth.consent.resource_catalog_scope_decision", "oauth.consent.agent_scope_refused", "oauth.consent.agent_subset_rejected", "oauth.consent.agent_scope_replace_suppressed", "oauth.consent.agent_scope_review_recorded", "oauth.consent.agent_scope_review_reminded", "oauth.token_grant_failed", "oauth.token_grant_denied", "oauth.token.resource_bound", "oauth.token.resource_rejected", "oauth.authorize.resource_rejected", "oauth.authorize.scope_rejected", "oauth.custom_scope.cascade_revoked", "oauth.resumption_redirect", "oauth.resumption_ticket_consumed", "oauth.resumption_rejected", "auth.mfa_login", "auth.saml_init", "auth.saml_acs_received", "auth.saml_acs_failed", "sso.jit_provisioned", "sso.email_mismatch", "sso.connection_created", "sso.connection_updated", "sso.connection_deleted", "sso.connection_activated", "sso.connection_deactivated", "sso.jit_disabled_blocked", "sso.attribute_updated", "sso.group_mapped", "sso.domain_added", "sso.domain_removed", "sso.bypass_code_used", "sso.groups_overage", "sso.email_unverified_skip", "sso.login_enforced_social", "sso.login_enforced", "eudi.signup_blocked", "anon_claim_password.signup_blocked", "anon_claim_social.signup_blocked", "social_oauth.signup_blocked", "scim.user_provisioned", "scim.user_deprovisioned", "scim.user_updated", "scim.user_reprovisioned", "scim.gdpr_conflict", "scim.token_created", "scim.token_rotated", "scim.token_revoked", "scim.groups_overage", "scim.bulk_deactivation_blocked", "scim.role_mapping_created", "scim.role_mapping_updated", "scim.role_mapping_deleted", "scim.admin_role_assignment_blocked", "scim.admin_role_assignment_granted", "scim.admin_role_assignment_revoked", "feature_flag.created", "feature_flag.updated", "feature_flag.deleted", "feature_flag.targeting_orphan_detected", "feature_flag.targeting_rule_updated", "feature_flag.targeting_membership_transferred", "baas.connect_initiated", "baas.connected", "baas.disconnected", "baas.checkout_created", "subscription.created", "subscription.updated", "baas.checkout_initiated", "baas.portal_accessed", "auth.passkey.registered", "auth.passkey.deleted", "auth.passkey.renamed", "auth.passkey.authenticated", "auth.passkey.sign_count_anomaly", "auth.passkey.step_up_issued", "auth.passkey.step_up_failed", "auth.passkey.feature_flag_toggled", "auth.register.blocked_disposable", "auth.register.blocked_subaddress", "auth.register.blocked_custom_blocklist", "auth.anonymous_login", "auth.anonymous_claimed", "auth.anonymous_purged", "auth.account_linked", "auth.account_unlinked", "auth.account_linking_cooldown_blocked", "auth.account_linking_cooldown_skipped", "auth.account_linking_mfa_step_up_required", "auth.account_linking_mfa_step_up_succeeded", "auth.account_linking_mfa_step_up_unavailable", "auth.account_linking_link_state_expired_rejected", "auth.account_linking_notification_enqueued", "dashboard.impersonation.started", "auth.sms_otp_requested", "auth.sms_otp_login", "auth.sms_otp_failed", "auth.sms_otp_exhausted", "auth.sms_otp_disabled", "auth.sms_otp_quota_exhausted", "auth.phone_verify_requested", "auth.phone_verified", "tenant.sms_otp_toggled", "auth.step_up_magic_link_initiated", "auth.step_up_email_otp_initiated", "auth.step_up_passkey_options_issued", "auth.step_up_issued", "auth.step_up_failed", "oauth.device.approved", "oauth.device.code_issued", "oauth.device.denied", "oauth.device.token_issued", "oauth.device.expired", "oauth.device.rate_limited", "oauth.token_exchange.issued", "oauth.token_exchange.subject_invalid", "oauth.token_exchange.scope_denied", "oauth.token_exchange.rate_limited", "oauth.token_exchange.client_unauthorized", "oauth.token_exchange.client_disabled", "oauth.token_exchange.revocation_requested", "oauth.token_exchange.authority_read_failed", "oauth.ciba.request_issued", "oauth.ciba.user_cap_reached", "oauth.ciba.rate_limited", "oauth.ciba.unknown_user", "oauth.ciba.approved", "oauth.ciba.denied", "oauth.ciba.expired", "oauth.ciba.token_issued", "oauth.ciba.replay_attempt", "oauth.ciba.scope_denied", "oauth.ciba.notification_delivery_failed", "agent.created", "agent.updated", "agent.secret_rotated", "agent.revoked", "agent.user_revoked", "agent.user_restored", "agent.rate_limited", "agent.concurrent_token_limit_reached", "agent.token_blocked_user_revoked", "agent.dcr_registered", "agent.dcr_read", "agent.dcr_updated", "agent.dcr_deleted", "auth_hook.created", "auth_hook.updated", "auth_hook.deleted", "auth_hook.secret_rotated", "auth_hook.enabled_changed", "auth_hook.executed", "auth_hook.execution_failed", "auth_hook.budget_exhausted", "auth_hook.circuit_breaker_opened", "auth_hook.auto_disabled", "auth_hook.reactivated", "auth_hook.claim_override_attempt", "auth_hook.violation", "auth_hook.tenant_rate_limited", "auth_hook.slow_warning", "auth_hook.concurrent_limit_reached", "auth_hook.tested", "auth_hook.circuit_breaker_reset", "auth_hook.marketplace_installed", "auth_hook.marketplace_uninstalled", "auth_hook.marketplace_paused", "auth_hook.marketplace_resumed", "auth_hook.marketplace_config_updated", "auth_hook.marketplace_credentials_rotated", "auth_hook.marketplace_executed", "auth_hook.marketplace_auto_disabled", "auth_hook.marketplace_circuit_breaker_reset", "auth_hook.marketplace_oauth_refresh_failed", "auth_hook.marketplace_test_executed", "eudi.login.initiated", "eudi.login.verified", "eudi.login.rejected", "eudi.age_check.initiated", "eudi.age_check.verified", "eudi.age_check.rejected", "vc.config.dpia_acknowledged", "vc.config.bootstrap_failed", "vc.offer.created", "vc.offer.replay_storm", "vc.exchange.accepted", "vc.exchange.rejected", "vc.exchange.completed", "vc.exchange.rejected_by_wallet", "vc.credential.issued", "vc.credential.revoked", "vc.credential.revoke_idempotent", "vc.issue.rejected", "vc.issue.age_unverifiable", "vc.status_list.signed", "vc.status_list.served", "vc.status_list.full", "vc.well_known.unreachable_external", "vc.tenant.offboarded", "vc.proof.alg_rejected", "vc.proof.replay_rejected", "vc.did.published_hash", "tenant.vc_config.minor_attestation_enabled", "tenant.vc_config.schema_changed", "tenant.vc_config.pepper_rotated", "auth.dpop_token_issued", "auth.dpop_token_validated", "auth.dpop_proof_mismatch", "auth.dpop_replay_detected", "auth.dpop_nonce_required", "auth.dpop_nonce_unavailable", "auth.dpop_config_changed", "auth.dpop_alg_rejected", "auth.dpop_proof_absent_observe", "auth.dpop_clock_skew_warning", "auth.dpop_jkt_churn_high", "auth.dpop_concurrent_use_detected", "auth.dpop_refresh_key_rotated", "auth.ssf_set_signed", "auth.ssf_set_delivered", "auth.ssf_set_delivery_failed", "auth.ssf_stream_breaker_opened", "auth.ssf_stream_breaker_closed", "auth.ssf_set_received", "auth.ssf_set_rejected_signature", "auth.ssf_set_rejected_replay", "auth.ssf_set_no_local_match", "auth.ssf_action_applied", "auth.ssf_verification_round_trip_completed", "auth.ssf_stream_created", "auth.ssf_stream_updated", "auth.ssf_stream_deleted", "auth.ssf_subject_added", "auth.ssf_subject_removed", "auth.ssf_session_revoked_applied", "auth.ssf_emit_dropped", "auth.session_validation_check_unavailable", "auth.refresh_revocation_check_unavailable", "auth.refresh_idempotent_retry", "auth.jwks_fetch_check_unavailable", "auth.agent_denylist_check_unavailable", "vc.config_check_unavailable", "auth.eudi_status_list_check_unavailable", "auth.eudi_pid_erased", "auth.rate_limited", "infra.cron_reaper_heartbeat", "resource_scope_catalog.deleted", "tenant.magic_link_toggled", "tenant.email_otp_toggled", "tenant.explicit_account_linking_toggled", "tenant.sms_allowed_countries_updated" ] }, "required": false, "name": "event_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "success", "failure" ] }, "required": false, "name": "result", "in": "query" } ], "responses": { "200": { "description": "Paginated list of audit events", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "ip_hash": { "type": "string" }, "user_agent_hash": { "type": "string" }, "result": { "type": "string" }, "actor": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "event_type", "actor", "metadata", "created_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/events/export": { "get": { "tags": [ "Events" ], "summary": "Export audit events as streaming CSV", "description": "Returns CSV with columns: event_type, user_id, ip_hash, user_agent_hash, result, created_at. Max 90-day range, max 500k rows.", "operationId": "exportEvents", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "required": true, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": true, "name": "to", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "user_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "tenant.billing_archived", "user.created", "user.deleted", "user.blocked", "user.unblocked", "user.updated", "user.came_of_age", "auth.login", "auth.failed", "auth.password_changed", "compliance.data_exported", "compliance.events_exported", "compliance.deletion_certificate", "compliance.parental_consent_obtained", "compliance.guardian_action", "tenant.deleted", "user.import", "user.import_preview", "import.welcome_emails_queued", "trial.expired", "trial.day0_email", "trial.day3_email", "trial.day7_email", "trial.day11_email", "trial.day15_email", "mau.alert_95", "payment.failed", "payment.authentication_required", "payment.dispute_created", "payment.dispute_closed", "subscription.past_due", "subscription.recovered", "subscription.cancelled", "plan.change_initiated", "billing.withdrawal_waiver", "invoice.paid", "billing.upgrade_survey", "billing.survey_response", "billing.renewal_reminder", "auth.magic_link_requested", "auth.magic_link_login", "auth.magic_link_scanner_detected", "auth.magic_link_ip_mismatch", "auth.email_auto_verified", "auth.email_otp_requested", "auth.email_otp_login", "auth.email_otp_failed", "auth.email_otp_exhausted", "auth.email_otp_disabled", "tenant.settings_updated", "oauth.token_issued", "oauth.token_refreshed", "oauth.code_issued", "oauth.consent_granted", "oauth.token_revoked", "oauth_client.scopes_updated", "oauth_consent.scope_change_declined", "oauth.consent.agent_scope_decision", "oauth.consent.resource_catalog_scope_decision", "oauth.consent.agent_scope_refused", "oauth.consent.agent_subset_rejected", "oauth.consent.agent_scope_replace_suppressed", "oauth.consent.agent_scope_review_recorded", "oauth.consent.agent_scope_review_reminded", "oauth.token_grant_failed", "oauth.token_grant_denied", "oauth.token.resource_bound", "oauth.token.resource_rejected", "oauth.authorize.resource_rejected", "oauth.authorize.scope_rejected", "oauth.custom_scope.cascade_revoked", "oauth.resumption_redirect", "oauth.resumption_ticket_consumed", "oauth.resumption_rejected", "auth.mfa_login", "auth.saml_init", "auth.saml_acs_received", "auth.saml_acs_failed", "sso.jit_provisioned", "sso.email_mismatch", "sso.connection_created", "sso.connection_updated", "sso.connection_deleted", "sso.connection_activated", "sso.connection_deactivated", "sso.jit_disabled_blocked", "sso.attribute_updated", "sso.group_mapped", "sso.domain_added", "sso.domain_removed", "sso.bypass_code_used", "sso.groups_overage", "sso.email_unverified_skip", "sso.login_enforced_social", "sso.login_enforced", "eudi.signup_blocked", "anon_claim_password.signup_blocked", "anon_claim_social.signup_blocked", "social_oauth.signup_blocked", "scim.user_provisioned", "scim.user_deprovisioned", "scim.user_updated", "scim.user_reprovisioned", "scim.gdpr_conflict", "scim.token_created", "scim.token_rotated", "scim.token_revoked", "scim.groups_overage", "scim.bulk_deactivation_blocked", "scim.role_mapping_created", "scim.role_mapping_updated", "scim.role_mapping_deleted", "scim.admin_role_assignment_blocked", "scim.admin_role_assignment_granted", "scim.admin_role_assignment_revoked", "feature_flag.created", "feature_flag.updated", "feature_flag.deleted", "feature_flag.targeting_orphan_detected", "feature_flag.targeting_rule_updated", "feature_flag.targeting_membership_transferred", "baas.connect_initiated", "baas.connected", "baas.disconnected", "baas.checkout_created", "subscription.created", "subscription.updated", "baas.checkout_initiated", "baas.portal_accessed", "auth.passkey.registered", "auth.passkey.deleted", "auth.passkey.renamed", "auth.passkey.authenticated", "auth.passkey.sign_count_anomaly", "auth.passkey.step_up_issued", "auth.passkey.step_up_failed", "auth.passkey.feature_flag_toggled", "auth.register.blocked_disposable", "auth.register.blocked_subaddress", "auth.register.blocked_custom_blocklist", "auth.anonymous_login", "auth.anonymous_claimed", "auth.anonymous_purged", "auth.account_linked", "auth.account_unlinked", "auth.account_linking_cooldown_blocked", "auth.account_linking_cooldown_skipped", "auth.account_linking_mfa_step_up_required", "auth.account_linking_mfa_step_up_succeeded", "auth.account_linking_mfa_step_up_unavailable", "auth.account_linking_link_state_expired_rejected", "auth.account_linking_notification_enqueued", "dashboard.impersonation.started", "auth.sms_otp_requested", "auth.sms_otp_login", "auth.sms_otp_failed", "auth.sms_otp_exhausted", "auth.sms_otp_disabled", "auth.sms_otp_quota_exhausted", "auth.phone_verify_requested", "auth.phone_verified", "tenant.sms_otp_toggled", "auth.step_up_magic_link_initiated", "auth.step_up_email_otp_initiated", "auth.step_up_passkey_options_issued", "auth.step_up_issued", "auth.step_up_failed", "oauth.device.approved", "oauth.device.code_issued", "oauth.device.denied", "oauth.device.token_issued", "oauth.device.expired", "oauth.device.rate_limited", "oauth.token_exchange.issued", "oauth.token_exchange.subject_invalid", "oauth.token_exchange.scope_denied", "oauth.token_exchange.rate_limited", "oauth.token_exchange.client_unauthorized", "oauth.token_exchange.client_disabled", "oauth.token_exchange.revocation_requested", "oauth.token_exchange.authority_read_failed", "oauth.ciba.request_issued", "oauth.ciba.user_cap_reached", "oauth.ciba.rate_limited", "oauth.ciba.unknown_user", "oauth.ciba.approved", "oauth.ciba.denied", "oauth.ciba.expired", "oauth.ciba.token_issued", "oauth.ciba.replay_attempt", "oauth.ciba.scope_denied", "oauth.ciba.notification_delivery_failed", "agent.created", "agent.updated", "agent.secret_rotated", "agent.revoked", "agent.user_revoked", "agent.user_restored", "agent.rate_limited", "agent.concurrent_token_limit_reached", "agent.token_blocked_user_revoked", "agent.dcr_registered", "agent.dcr_read", "agent.dcr_updated", "agent.dcr_deleted", "auth_hook.created", "auth_hook.updated", "auth_hook.deleted", "auth_hook.secret_rotated", "auth_hook.enabled_changed", "auth_hook.executed", "auth_hook.execution_failed", "auth_hook.budget_exhausted", "auth_hook.circuit_breaker_opened", "auth_hook.auto_disabled", "auth_hook.reactivated", "auth_hook.claim_override_attempt", "auth_hook.violation", "auth_hook.tenant_rate_limited", "auth_hook.slow_warning", "auth_hook.concurrent_limit_reached", "auth_hook.tested", "auth_hook.circuit_breaker_reset", "auth_hook.marketplace_installed", "auth_hook.marketplace_uninstalled", "auth_hook.marketplace_paused", "auth_hook.marketplace_resumed", "auth_hook.marketplace_config_updated", "auth_hook.marketplace_credentials_rotated", "auth_hook.marketplace_executed", "auth_hook.marketplace_auto_disabled", "auth_hook.marketplace_circuit_breaker_reset", "auth_hook.marketplace_oauth_refresh_failed", "auth_hook.marketplace_test_executed", "eudi.login.initiated", "eudi.login.verified", "eudi.login.rejected", "eudi.age_check.initiated", "eudi.age_check.verified", "eudi.age_check.rejected", "vc.config.dpia_acknowledged", "vc.config.bootstrap_failed", "vc.offer.created", "vc.offer.replay_storm", "vc.exchange.accepted", "vc.exchange.rejected", "vc.exchange.completed", "vc.exchange.rejected_by_wallet", "vc.credential.issued", "vc.credential.revoked", "vc.credential.revoke_idempotent", "vc.issue.rejected", "vc.issue.age_unverifiable", "vc.status_list.signed", "vc.status_list.served", "vc.status_list.full", "vc.well_known.unreachable_external", "vc.tenant.offboarded", "vc.proof.alg_rejected", "vc.proof.replay_rejected", "vc.did.published_hash", "tenant.vc_config.minor_attestation_enabled", "tenant.vc_config.schema_changed", "tenant.vc_config.pepper_rotated", "auth.dpop_token_issued", "auth.dpop_token_validated", "auth.dpop_proof_mismatch", "auth.dpop_replay_detected", "auth.dpop_nonce_required", "auth.dpop_nonce_unavailable", "auth.dpop_config_changed", "auth.dpop_alg_rejected", "auth.dpop_proof_absent_observe", "auth.dpop_clock_skew_warning", "auth.dpop_jkt_churn_high", "auth.dpop_concurrent_use_detected", "auth.dpop_refresh_key_rotated", "auth.ssf_set_signed", "auth.ssf_set_delivered", "auth.ssf_set_delivery_failed", "auth.ssf_stream_breaker_opened", "auth.ssf_stream_breaker_closed", "auth.ssf_set_received", "auth.ssf_set_rejected_signature", "auth.ssf_set_rejected_replay", "auth.ssf_set_no_local_match", "auth.ssf_action_applied", "auth.ssf_verification_round_trip_completed", "auth.ssf_stream_created", "auth.ssf_stream_updated", "auth.ssf_stream_deleted", "auth.ssf_subject_added", "auth.ssf_subject_removed", "auth.ssf_session_revoked_applied", "auth.ssf_emit_dropped", "auth.session_validation_check_unavailable", "auth.refresh_revocation_check_unavailable", "auth.refresh_idempotent_retry", "auth.jwks_fetch_check_unavailable", "auth.agent_denylist_check_unavailable", "vc.config_check_unavailable", "auth.eudi_status_list_check_unavailable", "auth.eudi_pid_erased", "auth.rate_limited", "infra.cron_reaper_heartbeat", "resource_scope_catalog.deleted", "tenant.magic_link_toggled", "tenant.email_otp_toggled", "tenant.explicit_account_linking_toggled", "tenant.sms_allowed_countries_updated" ] }, "required": false, "name": "event_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "success", "failure" ] }, "required": false, "name": "result", "in": "query" } ], "responses": { "200": { "description": "Streaming CSV with audit events", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited or export in progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/events/{id}": { "get": { "tags": [ "Events" ], "summary": "Get audit event detail", "operationId": "getEvent", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Audit event detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "ip_hash": { "type": "string" }, "user_agent_hash": { "type": "string" }, "result": { "type": "string" }, "actor": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "event_type", "actor", "metadata", "created_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Event not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/plan": { "get": { "tags": [ "billing" ], "summary": "Get current billing plan and limits", "operationId": "getBillingPlan", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to query billing for" }, "required": true, "description": "Tenant ID to query billing for", "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Current billing plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPlanResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/usage": { "get": { "tags": [ "billing" ], "summary": "Get current MAU usage and limits", "operationId": "getBillingUsage", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to query billing for" }, "required": true, "description": "Tenant ID to query billing for", "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Current usage metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingUsageResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/checkout": { "post": { "tags": [ "billing" ], "summary": "Create a checkout session for plan upgrade", "operationId": "createBillingCheckout", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to query billing for" }, "required": true, "description": "Tenant ID to query billing for", "name": "tenant_id", "in": "query" }, { "schema": { "type": "string", "description": "Optional opaque token (use a fresh UUIDv4 per logical operation) to deduplicate retries of this mutation. Reusing a value within the configured retention window (default 24h) replays the prior 2xx response — byte-identical body and original status — regardless of the request body. Authentication and tenant-membership checks always run before the idempotency cache is consulted: an Idempotency-Key never bypasses 401/403/404. Only 2xx responses are recorded; a 4xx/5xx (including 429) leaves no row, so a retry after a transient failure is a fresh attempt. Concurrent in-flight retries with the same key may both execute — the unique index dedups the stored result, the route-level advisory lock dedups the side effect. The dedup scope is (tenant, key, method, path)." }, "required": false, "description": "Optional opaque token (use a fresh UUIDv4 per logical operation) to deduplicate retries of this mutation. Reusing a value within the configured retention window (default 24h) replays the prior 2xx response — byte-identical body and original status — regardless of the request body. Authentication and tenant-membership checks always run before the idempotency cache is consulted: an Idempotency-Key never bypasses 401/403/404. Only 2xx responses are recorded; a 4xx/5xx (including 429) leaves no row, so a retry after a transient failure is a fresh attempt. Concurrent in-flight retries with the same key may both execute — the unique index dedups the stored result, the route-level advisory lock dedups the side effect. The dedup scope is (tenant, key, method, path).", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "pro", "business" ] }, "interval": { "type": "string", "enum": [ "monthly", "annual" ] }, "success_url": { "type": "string", "format": "uri" }, "cancel_url": { "type": "string", "format": "uri" }, "withdrawal_waiver": { "type": "boolean", "enum": [ true ] } }, "required": [ "plan", "interval", "success_url", "cancel_url", "withdrawal_waiver" ] } } } }, "responses": { "201": { "description": "Checkout session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "url": { "type": "string" }, "proration_amount_cents": { "type": "number" } }, "required": [ "session_id", "url" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/downgrade": { "post": { "tags": [ "billing" ], "summary": "Schedule plan downgrade at end of billing period", "operationId": "scheduleBillingDowngrade", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to query billing for" }, "required": true, "description": "Tenant ID to query billing for", "name": "tenant_id", "in": "query" }, { "schema": { "type": "string", "description": "Optional opaque token (use a fresh UUIDv4 per logical operation) to deduplicate retries of this mutation. Reusing a value within the configured retention window (default 24h) replays the prior 2xx response — byte-identical body and original status — regardless of the request body. Authentication and tenant-membership checks always run before the idempotency cache is consulted: an Idempotency-Key never bypasses 401/403/404. Only 2xx responses are recorded; a 4xx/5xx (including 429) leaves no row, so a retry after a transient failure is a fresh attempt. Concurrent in-flight retries with the same key may both execute — the unique index dedups the stored result, the route-level advisory lock dedups the side effect. The dedup scope is (tenant, key, method, path)." }, "required": false, "description": "Optional opaque token (use a fresh UUIDv4 per logical operation) to deduplicate retries of this mutation. Reusing a value within the configured retention window (default 24h) replays the prior 2xx response — byte-identical body and original status — regardless of the request body. Authentication and tenant-membership checks always run before the idempotency cache is consulted: an Idempotency-Key never bypasses 401/403/404. Only 2xx responses are recorded; a 4xx/5xx (including 429) leaves no row, so a retry after a transient failure is a fresh attempt. Concurrent in-flight retries with the same key may both execute — the unique index dedups the stored result, the route-level advisory lock dedups the side effect. The dedup scope is (tenant, key, method, path).", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "target_plan": { "type": "string", "enum": [ "free", "pro" ] } }, "required": [ "target_plan" ] } } } }, "responses": { "200": { "description": "Downgrade scheduled", "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string" }, "effective_at": { "type": "string" }, "impact": {} }, "required": [ "scheduled_at", "effective_at" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "billing" ], "summary": "Cancel pending plan downgrade", "operationId": "cancelBillingDowngrade", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to query billing for" }, "required": true, "description": "Tenant ID to query billing for", "name": "tenant_id", "in": "query" }, { "schema": { "type": "string", "description": "Optional opaque token (use a fresh UUIDv4 per logical operation) to deduplicate retries of this mutation. Reusing a value within the configured retention window (default 24h) replays the prior 2xx response — byte-identical body and original status — regardless of the request body. Authentication and tenant-membership checks always run before the idempotency cache is consulted: an Idempotency-Key never bypasses 401/403/404. Only 2xx responses are recorded; a 4xx/5xx (including 429) leaves no row, so a retry after a transient failure is a fresh attempt. Concurrent in-flight retries with the same key may both execute — the unique index dedups the stored result, the route-level advisory lock dedups the side effect. The dedup scope is (tenant, key, method, path)." }, "required": false, "description": "Optional opaque token (use a fresh UUIDv4 per logical operation) to deduplicate retries of this mutation. Reusing a value within the configured retention window (default 24h) replays the prior 2xx response — byte-identical body and original status — regardless of the request body. Authentication and tenant-membership checks always run before the idempotency cache is consulted: an Idempotency-Key never bypasses 401/403/404. Only 2xx responses are recorded; a 4xx/5xx (including 429) leaves no row, so a retry after a transient failure is a fresh attempt. Concurrent in-flight retries with the same key may both execute — the unique index dedups the stored result, the route-level advisory lock dedups the side effect. The dedup scope is (tenant, key, method, path).", "name": "Idempotency-Key", "in": "header" } ], "responses": { "204": { "description": "Pending downgrade cancelled" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/interval": { "post": { "tags": [ "billing" ], "summary": "Switch billing interval (monthly/annual)", "operationId": "switchBillingInterval", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to query billing for" }, "required": true, "description": "Tenant ID to query billing for", "name": "tenant_id", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "interval": { "type": "string", "enum": [ "monthly", "annual" ] } }, "required": [ "interval" ] } } } }, "responses": { "200": { "description": "Interval switched", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "current_period_end": { "type": "string" } }, "required": [ "status", "current_period_end" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/portal": { "post": { "tags": [ "billing" ], "summary": "Create Stripe Customer Portal session", "operationId": "createBillingPortal", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to query billing for" }, "required": true, "description": "Tenant ID to query billing for", "name": "tenant_id", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "return_url": { "type": "string", "format": "uri" }, "flow_data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment_method_update" ] } } } }, "required": [ "return_url" ] } } } }, "responses": { "200": { "description": "Portal session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/overage": { "post": { "tags": [ "billing" ], "summary": "Purchase or update MAU overage blocks", "operationId": "updateBillingOverage", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to query billing for" }, "required": true, "description": "Tenant ID to query billing for", "name": "tenant_id", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "blocks": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "blocks" ] } } } }, "responses": { "200": { "description": "Overage updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "blocks": { "type": "number" }, "effective_mau_limit": { "type": "number" }, "max_blocks": { "type": "number" }, "price_per_block": { "type": "number" } }, "required": [ "blocks", "effective_mau_limit", "max_blocks", "price_per_block" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "billing" ], "summary": "Get MAU overage block status", "operationId": "getBillingOverage", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to query billing for" }, "required": true, "description": "Tenant ID to query billing for", "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Overage status", "content": { "application/json": { "schema": { "type": "object", "properties": { "blocks": { "type": "number" }, "effective_mau_limit": { "type": "number" }, "max_blocks": { "type": "number" }, "price_per_block": { "type": "number" } }, "required": [ "blocks", "effective_mau_limit", "max_blocks", "price_per_block" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/subscription": { "delete": { "tags": [ "billing" ], "summary": "Cancel subscription", "operationId": "cancelBillingSubscription", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to query billing for" }, "required": true, "description": "Tenant ID to query billing for", "name": "tenant_id", "in": "query" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancellation_reason": { "type": "string", "enum": [ "too_expensive", "missing_features", "switched_service", "unused", "other" ] }, "cancel_at_period_end": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Subscription cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled_at": { "type": "string" }, "effective_plan": { "type": "string" } }, "required": [ "cancelled_at", "effective_plan" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/checkout-sessions/{session_id}": { "get": { "tags": [ "billing" ], "summary": "Verify a Stripe Checkout Session for the caller's tenant", "operationId": "getCheckoutSession", "parameters": [ { "schema": { "type": "string", "minLength": 1, "pattern": "^cs_", "description": "Stripe Checkout Session ID (cs_…)" }, "required": true, "description": "Stripe Checkout Session ID (cs_…)", "name": "session_id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to verify session ownership against" }, "required": true, "description": "Tenant ID to verify session ownership against", "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Checkout session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionVerifyResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Session not found or belongs to another tenant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/invoices": { "get": { "tags": [ "billing" ], "summary": "List invoices for a tenant across active payment provider + Fakturownia VAT enrichment", "operationId": "listBillingInvoices", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID to list invoices for" }, "required": true, "description": "Tenant ID to list invoices for", "name": "tenant_id", "in": "query" }, { "schema": { "type": "string", "description": "Opaque pagination cursor from a prior response" }, "required": false, "description": "Opaque pagination cursor from a prior response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (default 20, max 100)" }, "required": false, "description": "Page size (default 20, max 100)", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "Paginated invoice list", "headers": { "Cache-Control": { "description": "Per RFC 9111 — private, short max-age, must-revalidate.", "schema": { "type": "string" } }, "ETag": { "description": "Strong ETag for conditional GET; If-None-Match → 304.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 3 }, "provider": { "type": "string", "enum": [ "stripe", "polar", "creem", "fakturownia" ] }, "document_type": { "type": "string", "enum": [ "stripe_receipt", "stripe_invoice", "polar_invoice", "creem_invoice", "fakturownia_vat_invoice", "credit_note" ] }, "legal_role": { "type": "string", "enum": [ "primary_legal", "supplementary_receipt" ] }, "issued_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$" }, "period_start": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$" }, "period_end": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$" }, "amount_cents": { "type": "integer" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "status": { "type": "string", "enum": [ "paid", "open", "void", "uncollectible" ] }, "customer_tax_country": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" }, "customer_nip": { "type": [ "string", "null" ] }, "customer_contact_status": { "type": "string", "enum": [ "present", "erased_per_art17" ] }, "ksef_gov_id": { "type": [ "string", "null" ] }, "ksef_status": { "type": [ "string", "null" ], "enum": [ "pending", "accepted", "rejected", "not_applicable", "offline_emergency_issued_awaiting_resubmission", "pre_mandate", null ] }, "document_kind": { "type": "string", "enum": [ "ksef_invoice", "foreign_b2b_invoice", "b2c_receipt", "pending", "unavailable" ] }, "invoice_number": { "type": [ "string", "null" ] }, "corrects_invoice_id": { "type": [ "string", "null" ] }, "corrected_by_invoice_id": { "type": [ "string", "null" ] }, "structured_xml_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "provider", "document_type", "legal_role", "issued_at", "period_start", "period_end", "amount_cents", "currency", "status", "customer_tax_country", "customer_nip", "customer_contact_status", "ksef_gov_id", "ksef_status", "document_kind", "invoice_number", "corrects_invoice_id", "corrected_by_invoice_id", "structured_xml_url" ], "additionalProperties": false } }, "cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "degraded_providers": { "type": "array", "items": { "type": "string", "enum": [ "stripe", "polar", "creem", "fakturownia" ] } } }, "required": [ "items", "cursor", "has_more", "degraded_providers" ], "additionalProperties": false } } } }, "304": { "description": "Not Modified — list unchanged since If-None-Match" }, "400": { "description": "Invalid cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found / cross-tenant access", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/invoices/{invoice_id}/download-url": { "post": { "tags": [ "billing" ], "summary": "Mint a short-lived signed download URL for an invoice (click-time only)", "operationId": "mintBillingInvoiceDownloadUrl", "parameters": [ { "schema": { "type": "string", "minLength": 3, "description": "Composite invoice id \"${provider}:${external_id}\"" }, "required": true, "description": "Composite invoice id \"${provider}:${external_id}\"", "name": "invoice_id", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Tenant scope for the download URL" }, "required": true, "description": "Tenant scope for the download URL", "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Signed download URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri", "description": "Single-use short-lived URL for this invoice" }, "expires_at": { "type": "string", "description": "ISO-8601 UTC expiry timestamp" } }, "required": [ "download_url", "expires_at" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant or invoice not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/invoices/download": { "get": { "tags": [ "billing" ], "summary": "Resolve a signed download token and 302-redirect (or stream PDF) to the invoice document", "operationId": "downloadBillingInvoice", "parameters": [ { "schema": { "type": "string", "minLength": 10, "description": "Signed download token from mint endpoint" }, "required": true, "description": "Signed download token from mint endpoint", "name": "token", "in": "query" } ], "responses": { "302": { "description": "Redirect to provider CDN URL", "headers": { "Location": { "description": "Provider-signed CDN URL", "schema": { "type": "string" } }, "Cache-Control": { "description": "no-store", "schema": { "type": "string" } }, "Referrer-Policy": { "description": "no-referrer", "schema": { "type": "string" } } } }, "404": { "description": "Invalid token / invoice not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "Signed download URL already consumed (single-use)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/connect": { "post": { "tags": [ "BaaS" ], "summary": "Initiate Stripe Connect OAuth", "operationId": "initiateBaasConnect", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "responses": { "200": { "description": "OAuth URL for Stripe Connect", "content": { "application/json": { "schema": { "type": "object", "properties": { "oauth_url": { "type": "string" } }, "required": [ "oauth_url" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "BaaS" ], "summary": "Get BaaS connection status", "operationId": "getBaasConnect", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Connection status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaasConnectionResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "BaaS" ], "summary": "Disconnect Stripe Connect", "operationId": "deleteBaasConnect", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "responses": { "204": { "description": "Disconnected" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/products": { "post": { "tags": [ "BaaS" ], "summary": "Create a billing product", "operationId": "createBaasProduct", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Product created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaasProductResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Stripe not connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "BaaS" ], "summary": "List billing products", "operationId": "listBaasProducts", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Products list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BaasProductResponse" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/products/{id}": { "patch": { "tags": [ "BaaS" ], "summary": "Update a billing product", "operationId": "updateBaasProduct", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Product updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaasProductResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "BaaS" ], "summary": "Delete a billing product", "operationId": "deleteBaasProduct", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Has active plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/plans": { "post": { "tags": [ "BaaS" ], "summary": "Create a billing plan", "operationId": "createBaasPlan", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "price_cents": { "type": "integer", "exclusiveMinimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "interval": { "type": "string", "enum": [ "monthly", "annual" ] }, "trial_days": { "type": "integer", "minimum": 0 }, "features": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20 }, "role_id": { "type": "string", "format": "uuid" }, "flag_keys": { "type": "array", "items": { "type": "string" } } }, "required": [ "product_id", "name", "price_cents", "currency", "interval" ] } } } }, "responses": { "201": { "description": "Plan created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaasPlanResponse" } } } }, "400": { "description": "Invalid flag keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Stripe not connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "BaaS" ], "summary": "List billing plans", "operationId": "listBaasPlans", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "product_id", "in": "query" } ], "responses": { "200": { "description": "Plans list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BaasPlanResponse" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/plans/{id}": { "patch": { "tags": [ "BaaS" ], "summary": "Update a billing plan (non-price fields only)", "operationId": "updateBaasPlan", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "features": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20 }, "trial_days": { "type": [ "integer", "null" ], "minimum": 0 }, "role_id": { "type": [ "string", "null" ], "format": "uuid" }, "flag_keys": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Plan updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaasPlanResponse" } } } }, "400": { "description": "Invalid flag keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "BaaS" ], "summary": "Deactivate a billing plan", "operationId": "deactivateBaasPlan", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deactivated" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Has active subscribers", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/checkout": { "post": { "tags": [ "BaaS" ], "summary": "Create Stripe Checkout session for an end-user", "operationId": "createBaasCheckout", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "plan_id": { "type": "string", "format": "uuid" }, "success_url": { "type": "string", "format": "uri" }, "cancel_url": { "type": "string", "format": "uri" } }, "required": [ "user_id", "plan_id", "success_url", "cancel_url" ] } } } }, "responses": { "200": { "description": "Checkout session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "url": { "type": "string" } }, "required": [ "session_id", "url" ] } } } }, "400": { "description": "Invalid URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Stripe not connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/subscriptions": { "get": { "tags": [ "BaaS" ], "summary": "List end-user subscriptions", "operationId": "listBaasSubscriptions", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "user_id", "in": "query" } ], "responses": { "200": { "description": "Subscriptions list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BaasSubscriptionResponse" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/subscriptions/{id}": { "get": { "tags": [ "BaaS" ], "summary": "Get a single subscription", "operationId": "getBaasSubscription", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaasSubscriptionResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/public-plans": { "get": { "tags": [ "BaaS" ], "summary": "List active billing plans (public)", "operationId": "listBaasPublicPlans", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Active plans list (public fields only)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BaasPublicPlanResponse" } } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/user/checkout": { "post": { "tags": [ "BaaS" ], "summary": "Create Stripe Checkout session for signed-in user", "operationId": "createBaasUserCheckout", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "format": "uuid" }, "success_url": { "type": "string", "format": "uri" }, "cancel_url": { "type": "string", "format": "uri" } }, "required": [ "plan_id", "success_url", "cancel_url" ] } } } }, "responses": { "201": { "description": "Checkout session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "url": { "type": "string" } }, "required": [ "session_id", "url" ] } } } }, "400": { "description": "Invalid URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Tenant or plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/user/subscription": { "get": { "tags": [ "BaaS" ], "summary": "Get signed-in user's subscription", "operationId": "getBaasUserSubscription", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaasSubscriptionResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No subscription found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/billing/baas/{slug}/user/portal": { "post": { "tags": [ "BaaS" ], "summary": "Create Stripe Customer Portal session for signed-in user", "operationId": "createBaasUserPortal", "parameters": [ { "schema": { "type": "string", "description": "Tenant slug" }, "required": true, "description": "Tenant slug", "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "return_url": { "type": "string", "format": "uri" } }, "required": [ "return_url" ] } } } }, "responses": { "201": { "description": "Portal session URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } }, "400": { "description": "Invalid return URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No subscription found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Stripe account inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/email-preferences/unsubscribe": { "post": { "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "required": true, "name": "token", "in": "query" } ], "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "List-Unsubscribe": { "type": "string" } } } } } }, "responses": { "200": { "description": "Unsubscribe processed (idempotent — returns 200 even if already unsubscribed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/billing/survey": { "get": { "tags": [ "billing" ], "summary": "Verify survey token and render confirmation page", "operationId": "getSurveyConfirmation", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "required": true, "name": "token", "in": "query" } ], "responses": { "200": { "description": "HTML confirmation page with auto-submit form", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Survey not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "billing" ], "summary": "Store upgrade motivation survey response", "operationId": "submitSurveyResponse", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Survey response recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "ok", "message" ] } } } }, "400": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Survey not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/saml/metadata": { "get": { "tags": [ "SAML" ], "summary": "SP metadata XML", "operationId": "getSamlMetadata", "responses": { "200": { "description": "SP metadata XML" } } } }, "/saml/init/:connectionId": { "get": { "tags": [ "SAML" ], "summary": "SP-initiated SSO redirect", "operationId": "getSamlInit", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "connectionId", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "return_url", "in": "query" } ], "responses": { "302": { "description": "Redirect to IdP SSO URL" }, "404": { "description": "Connection not found or inactive" } } } }, "/saml/acs": { "post": { "tags": [ "SAML" ], "summary": "SAML Assertion Consumer Service", "operationId": "postSamlAcs", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "302": { "description": "Redirect after successful assertion" }, "400": { "description": "Invalid SAML response" }, "413": { "description": "Payload too large" } } } }, "/sso/oidc/initiate": { "get": { "tags": [ "SSO OIDC" ], "summary": "OIDC SSO initiate — redirect to enterprise IdP", "operationId": "getOidcSsoInitiate", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "connection_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "return_url", "in": "query" } ], "responses": { "302": { "description": "Redirect to IdP authorization endpoint" }, "400": { "description": "Invalid connection or return_url" }, "404": { "description": "Connection not found" } } } }, "/sso/oidc/callback": { "get": { "tags": [ "SSO OIDC" ], "summary": "OIDC SSO callback — exchange code for session", "operationId": "getOidcSsoCallback", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "error", "in": "query" } ], "responses": { "302": { "description": "Redirect after successful authentication" }, "400": { "description": "Invalid state or authentication failed" } } } }, "/v1/sso/connections/:id/scim-tokens": { "post": { "tags": [ "SCIM Tokens" ], "summary": "Generate a SCIM Bearer token for this connection", "operationId": "createScimToken", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "label" ] } } } }, "responses": { "201": { "description": "Token created — raw token shown ONCE", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string" }, "label": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "id", "token", "label", "expires_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "SCIM Tokens" ], "summary": "List SCIM tokens for this connection", "operationId": "listScimTokens", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "List of SCIM tokens", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "last_used_at": { "type": "string" }, "expires_at": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "label", "created_at" ] } }, "active_count": { "type": "integer" }, "expired_count": { "type": "integer" } }, "required": [ "data", "active_count", "expired_count" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections/:id/scim-tokens/:tokenId": { "delete": { "tags": [ "SCIM Tokens" ], "summary": "Revoke a SCIM token", "operationId": "revokeScimToken", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "tokenId", "in": "path" } ], "responses": { "204": { "description": "Token revoked" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Token not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections/:id/role-mappings": { "post": { "tags": [ "SCIM Role Mappings" ], "summary": "Create an IdP group -> Rakomi role mapping for a SCIM connection", "operationId": "createScimRoleMapping", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idp_group_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role_id": { "type": "string", "format": "uuid" }, "allow_admin_assignment": { "type": "boolean" } }, "required": [ "idp_group_name", "role_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Mapping created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "idp_group_name": { "type": "string" }, "role_id": { "type": "string", "format": "uuid" }, "allow_admin_assignment": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "connection_id", "idp_group_name", "role_id", "allow_admin_assignment", "created_at" ] } } } }, "400": { "description": "Admin-assignment confirmation required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Connection or role not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Mapping already exists for this IdP group", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "SCIM Role Mappings" ], "summary": "List IdP group -> Rakomi role mappings for a SCIM connection", "operationId": "listScimRoleMappings", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List of role mappings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "idp_group_name": { "type": "string" }, "role_id": { "type": "string", "format": "uuid" }, "allow_admin_assignment": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "connection_id", "idp_group_name", "role_id", "allow_admin_assignment", "created_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/sso/connections/:id/role-mappings/:mappingId": { "patch": { "tags": [ "SCIM Role Mappings" ], "summary": "Partially update an IdP group -> Rakomi role mapping", "operationId": "updateScimRoleMapping", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "mappingId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idp_group_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role_id": { "type": "string", "format": "uuid" }, "allow_admin_assignment": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated mapping", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "idp_group_name": { "type": "string" }, "role_id": { "type": "string", "format": "uuid" }, "allow_admin_assignment": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "connection_id", "idp_group_name", "role_id", "allow_admin_assignment", "created_at" ] } } } }, "400": { "description": "Admin-assignment confirmation required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Connection, mapping or role not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Mapping already exists for this IdP group", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "SCIM Role Mappings" ], "summary": "Delete an IdP group -> Rakomi role mapping", "operationId": "deleteScimRoleMapping", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "mappingId", "in": "path" } ], "responses": { "204": { "description": "Mapping deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Mapping not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/scim/v2/ServiceProviderConfig": { "get": { "tags": [ "SCIM" ], "summary": "SCIM ServiceProviderConfig — SCIM capability declaration", "operationId": "getScimServiceProviderConfig", "responses": { "200": { "description": "SCIM ServiceProviderConfig", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": {} } } } } } } }, "/scim/v2/ResourceTypes": { "get": { "tags": [ "SCIM" ], "summary": "SCIM ResourceTypes — supported resource type declarations", "operationId": "getScimResourceTypes", "responses": { "200": { "description": "SCIM ResourceTypes", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": {} } } } } } } }, "/scim/v2/Schemas": { "get": { "tags": [ "SCIM" ], "summary": "SCIM Schemas — User and Group schema definitions", "operationId": "getScimSchemas", "responses": { "200": { "description": "SCIM Schemas", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": {} } } } } } } }, "/v1/flags/evaluate": { "post": { "tags": [ "Feature Flags" ], "summary": "Evaluate feature flags for a user context", "operationId": "evaluateFeatureFlags", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "description": "User ID for targeted evaluation" }, "user_metadata": { "type": "object", "additionalProperties": {}, "description": "User metadata for metadata_match rules" }, "keys": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$|^[a-z0-9]$" }, "maxItems": 100, "description": "Specific flag keys to evaluate (omit for all)" }, "include_reason": { "type": "boolean", "default": false, "description": "Include evaluation reason codes in response" } } } } } }, "responses": { "200": { "description": "Evaluated feature flags", "content": { "application/json": { "schema": { "type": "object", "properties": { "flags": { "type": "object", "additionalProperties": {} } }, "required": [ "flags" ] } } } }, "304": { "description": "Not Modified (ETag matched)" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/flags": { "post": { "tags": [ "Feature Flags" ], "summary": "Create a feature flag", "operationId": "createFeatureFlag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$|^[a-z0-9]$", "description": "Immutable flag key (slug format)", "example": "dark-mode" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Human-readable flag name", "example": "Dark Mode" }, "description": { "type": "string", "maxLength": 1000, "description": "Optional description" }, "type": { "type": "string", "enum": [ "boolean", "string", "number", "json" ], "description": "Flag value type" }, "default_value": { "description": "Default value when no rule matches; must match the flag type" }, "enabled": { "type": "boolean", "default": false }, "targeting_rules": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "all_users" ] }, "value": {} }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage" ] }, "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "value": {} }, "required": [ "type", "percentage" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user_list" ] }, "user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "minItems": 1, "maxItems": 1000 }, "value": {} }, "required": [ "type", "user_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "metadata_match" ] }, "metadata_key": { "type": "string", "maxLength": 100, "pattern": "^[a-zA-Z0-9_.]+$" }, "metadata_value": { "type": "string", "maxLength": 500 }, "value": {} }, "required": [ "type", "metadata_key", "metadata_value" ], "additionalProperties": false } ] }, "maxItems": 10 }, "expires_at": { "type": "string", "format": "date-time", "description": "Flag auto-disables after this timestamp (ISO 8601)" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 } }, "required": [ "key", "name", "type" ] } } } }, "responses": { "201": { "description": "Feature flag created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "boolean", "string", "number", "json" ] }, "default_value": {}, "enabled": { "type": "boolean" }, "targeting_rules": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "expires_at": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "name", "type", "enabled", "created_at", "updated_at" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit reached or type not allowed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Flag key already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Feature Flags" ], "summary": "List feature flags", "operationId": "listFeatureFlags", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tag", "in": "query" } ], "responses": { "200": { "description": "Feature flags list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "boolean", "string", "number", "json" ] }, "default_value": {}, "enabled": { "type": "boolean" }, "targeting_rules": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "expires_at": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "name", "type", "enabled", "created_at", "updated_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Invalid cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/flags/{id}": { "get": { "tags": [ "Feature Flags" ], "summary": "Get a feature flag", "operationId": "getFeatureFlag", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Feature flag ID" }, "required": true, "description": "Feature flag ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Feature flag", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "boolean", "string", "number", "json" ] }, "default_value": {}, "enabled": { "type": "boolean" }, "targeting_rules": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "expires_at": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "name", "type", "enabled", "created_at", "updated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Feature flag not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Feature Flags" ], "summary": "Update a feature flag", "operationId": "updateFeatureFlag", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Feature flag ID" }, "required": true, "description": "Feature flag ID", "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Ignored — key is immutable after creation" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "default_value": {}, "enabled": { "type": "boolean" }, "targeting_rules": { "type": [ "array", "null" ], "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "all_users" ] }, "value": {} }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage" ] }, "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "value": {} }, "required": [ "type", "percentage" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user_list" ] }, "user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "minItems": 1, "maxItems": 1000 }, "value": {} }, "required": [ "type", "user_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "metadata_match" ] }, "metadata_key": { "type": "string", "maxLength": 100, "pattern": "^[a-zA-Z0-9_.]+$" }, "metadata_value": { "type": "string", "maxLength": 500 }, "value": {} }, "required": [ "type", "metadata_key", "metadata_value" ], "additionalProperties": false } ] }, "maxItems": 10 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 } } } } } }, "responses": { "200": { "description": "Feature flag updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "boolean", "string", "number", "json" ] }, "default_value": {}, "enabled": { "type": "boolean" }, "targeting_rules": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "expires_at": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "name", "type", "enabled", "created_at", "updated_at" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan restriction (e.g. percentage rollout on Free)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Feature flag not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "key is immutable — use a different field", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Feature Flags" ], "summary": "Delete a feature flag", "operationId": "deleteFeatureFlag", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Feature flag ID" }, "required": true, "description": "Feature flag ID", "name": "id", "in": "path" } ], "responses": { "204": { "description": "Feature flag deleted" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Feature flag not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/switch": { "post": { "tags": [ "Organizations" ], "summary": "Switch active organization context", "operationId": "switchOrganization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchOrgRequest" } } } }, "responses": { "200": { "description": "New access token with updated org context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchOrgResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Policy violation (mfa_required, sso_required, email_domain_not_allowed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found or user not a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/validate-slug": { "get": { "tags": [ "Organizations" ], "summary": "Check if an org slug is available within a tenant", "operationId": "validateOrgSlug", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 63, "description": "Slug to check", "example": "my-team" }, "required": true, "description": "Slug to check", "name": "slug", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Tenant ID" }, "required": true, "description": "Tenant ID", "name": "tenant_id", "in": "query" } ], "responses": { "200": { "description": "Slug availability", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" } }, "required": [ "available" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/invitations/{token}/accept": { "post": { "tags": [ "Organizations" ], "summary": "Accept an org invitation (user must be logged in)", "operationId": "acceptOrgInvitation", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "token", "in": "path" } ], "responses": { "200": { "description": "Invitation accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string" }, "role": { "type": "string" } }, "required": [ "org_id", "role" ] } } } }, "401": { "description": "Not authenticated — register or login first", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Invitation not found or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Already a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations": { "post": { "tags": [ "Organizations" ], "summary": "Create a new organization", "operationId": "createOrganization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Acme Corp" }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$|^[a-z0-9]$", "example": "acme-corp" }, "logo_url": { "type": "string", "format": "uri" }, "metadata": { "type": "object", "additionalProperties": {} }, "enrollment_mode": { "type": "string", "enum": [ "invite_only", "public", "public_with_approval" ], "default": "invite_only" }, "allowed_email_domains": { "type": "array", "items": { "type": "string" } } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Organization created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Slug already in use", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}": { "get": { "tags": [ "Organizations" ], "summary": "Get organization by ID", "operationId": "getOrganization", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Organization ID" }, "required": true, "description": "Organization ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Organizations" ], "summary": "Update organization settings", "operationId": "updateOrganization", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$|^[a-z0-9]$" }, "logo_url": { "type": [ "string", "null" ], "format": "uri" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {} }, "enrollment_mode": { "type": "string", "enum": [ "invite_only", "public", "public_with_approval" ] }, "allowed_email_domains": { "type": [ "array", "null" ], "items": { "type": "string" } }, "max_members_override": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 } } } } } }, "responses": { "200": { "description": "Organization updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Slug already in use", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Organizations" ], "summary": "Delete an organization (Owner only)", "operationId": "deleteOrganization", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Organization deleted" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Owner role required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/members": { "get": { "tags": [ "Organizations" ], "summary": "List organization members (cursor-paginated)", "operationId": "listOrganizationMembers", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Members list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgMemberResponse" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/sso-connections": { "get": { "tags": [ "Organizations" ], "summary": "List SSO connections linked to an organization", "operationId": "listOrganizationSsoConnections", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "SSO connections for the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "last_used_at": { "type": "string" }, "idp_certificate_expires_at": { "type": "string" }, "idp_certificate_days_until_expiry": { "type": "integer" }, "error_message": { "type": "string" }, "users_count": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "type", "status", "users_count", "created_at", "updated_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/members/invite": { "post": { "tags": [ "Organizations" ], "summary": "Invite a user to the organization", "operationId": "inviteOrgMember", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "role": { "type": "string", "enum": [ "admin", "member" ], "default": "member" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "Invitation created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "invited_email": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "expires_at": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "org_id", "invited_email", "role", "status", "expires_at", "created_at" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Admin or Owner role required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Already a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Invitation rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/members/me": { "delete": { "tags": [ "Organizations" ], "summary": "Leave the organization (self-removal)", "operationId": "leaveOrganization", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Left organization" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found or not a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Last owner cannot leave — transfer ownership first", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/members/{user_id}": { "delete": { "tags": [ "Organizations" ], "summary": "Remove a member from the organization", "operationId": "removeOrgMember", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "user_id", "in": "path" } ], "responses": { "204": { "description": "Member removed" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization or member not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Last owner cannot be removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Organizations" ], "summary": "Update an org member role", "operationId": "updateOrgMemberRole", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "user_id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "membership_expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "responses": { "200": { "description": "Member updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgMemberResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization or member not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/members/{user_id}/metadata": { "get": { "tags": [ "Organizations" ], "summary": "Get membership metadata (private metadata visible to Owner/Admin only)", "operationId": "getOrgMemberMetadata", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "user_id", "in": "path" } ], "responses": { "200": { "description": "Membership metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "membership_public_metadata": {}, "membership_private_metadata": {} } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization or member not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Organizations" ], "summary": "Update membership metadata", "operationId": "updateOrgMemberMetadata", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "user_id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "membership_public_metadata": { "type": [ "object", "null" ], "additionalProperties": {} }, "membership_private_metadata": { "type": [ "object", "null" ], "additionalProperties": {} } } } } } }, "responses": { "200": { "description": "Metadata updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "membership_public_metadata": {}, "membership_private_metadata": {} } } } } }, "400": { "description": "membership_public_metadata exceeds the size/nesting limit or carries a disallowed key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization or member not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/transfer-ownership": { "post": { "tags": [ "Organizations" ], "summary": "Transfer organization ownership to another member", "operationId": "transferOrgOwnership", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_owner_user_id": { "type": "string", "format": "uuid" } }, "required": [ "new_owner_user_id" ] } } } }, "responses": { "200": { "description": "Ownership transferred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Owner role required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization or target member not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/join": { "post": { "tags": [ "Organizations" ], "summary": "Join an organization (public enrollment or submit join request for approval)", "operationId": "joinOrganization", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "201": { "description": "Joined organization directly (public enrollment)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "joined" ] }, "org_id": { "type": "string" } }, "required": [ "status", "org_id" ] } } } }, "202": { "description": "Join request submitted for approval", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending_approval" ] }, "request_id": { "type": "string" } }, "required": [ "status", "request_id" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Invite-only organization or email domain not allowed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Already a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Join rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/join-requests": { "get": { "tags": [ "Organizations" ], "summary": "List pending join requests (Owner/Admin only)", "operationId": "listOrgJoinRequests", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Join requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgJoinRequest" } } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Admin or Owner role required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/join-requests/{request_id}/{decision}": { "post": { "tags": [ "Organizations" ], "summary": "Approve or reject a join request (Owner/Admin only)", "operationId": "decideOrgJoinRequest", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "request_id", "in": "path" }, { "schema": { "type": "string", "enum": [ "approve", "reject" ] }, "required": true, "name": "decision", "in": "path" } ], "responses": { "200": { "description": "Decision recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Admin or Owner role required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization or join request not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/organizations/{id}/policy": { "get": { "tags": [ "Organizations" ], "summary": "Get organization authentication policy", "operationId": "getOrganizationPolicy", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Organization auth policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgAuthPolicyResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "put": { "tags": [ "Organizations" ], "summary": "Update organization authentication policy", "operationId": "updateOrganizationPolicy", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgAuthPolicyRequest" } } } }, "responses": { "200": { "description": "Updated organization auth policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgAuthPolicyResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden or plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/organizations": { "get": { "tags": [ "Organizations" ], "summary": "List the authenticated user's org memberships", "operationId": "listUserOrganizations", "responses": { "200": { "description": "User org memberships", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserOrgListItem" } } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/link/{provider}": { "post": { "tags": [ "users", "account-linking" ], "summary": "Initiate explicit linking of a provider identity to the authenticated user", "operationId": "initiateAccountLink", "parameters": [ { "schema": { "type": "string", "enum": [ "google", "github", "microsoft", "apple", "discord", "facebook", "slack", "twitter", "gitlab", "linkedin" ] }, "required": true, "name": "provider", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "mfa_verification_token": { "type": "string" } }, "required": [ "redirect_uri" ] } } } }, "responses": { "200": { "description": "Authorization URL to redirect the user to", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ], "default": "success" }, "authorization_url": { "type": "string", "format": "uri" } }, "required": [ "authorization_url" ] } } } }, "400": { "description": "Invalid redirect_uri", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Linking disabled or anonymous caller", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Provider not supported", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "users", "account-linking" ], "summary": "Unlink a federated identity from the authenticated user", "operationId": "unlinkAccountLink", "parameters": [ { "schema": { "type": "string", "enum": [ "google", "github", "microsoft", "apple", "discord", "facebook", "slack", "twitter", "gitlab", "linkedin" ] }, "required": true, "name": "provider", "in": "path" } ], "responses": { "200": { "description": "Unlink succeeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "unlinked": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "google", "github", "microsoft", "apple", "discord", "facebook", "slack", "twitter", "gitlab", "linkedin" ] }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "only_password_remains" ] }, "default": [] } }, "required": [ "unlinked", "provider" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Anonymous caller", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Identity not found or provider unsupported", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Cannot unlink last login method", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/users/me/link": { "get": { "tags": [ "users", "account-linking" ], "summary": "List the authenticated user’s linked login methods", "operationId": "listAccountLinks", "responses": { "200": { "description": "Linked methods for the caller", "content": { "application/json": { "schema": { "type": "object", "properties": { "methods": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "password" ] }, "active": { "type": "boolean" } }, "required": [ "kind", "active" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "social" ] }, "provider": { "type": "string", "enum": [ "google", "github", "microsoft", "apple", "discord", "facebook", "slack", "twitter", "gitlab", "linkedin" ] }, "provider_email_hash": { "type": "string" }, "linked_at": { "type": "string" }, "linked_via": { "type": "string", "enum": [ "signup", "explicit_link", "automatic_link" ] } }, "required": [ "kind", "provider", "provider_email_hash", "linked_at", "linked_via" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "passkey" ] }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "kind", "count" ] } ] } }, "cooldown_until": { "type": [ "string", "null" ] } }, "required": [ "methods", "cooldown_until" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Anonymous caller", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers": { "post": { "tags": [ "Publishers" ], "summary": "Create a publisher account + founding owner membership", "operationId": "createPublisher", "parameters": [ { "schema": { "type": "string", "maxLength": 255, "description": "Optional opaque token to deduplicate retries of publisher creation. Namespaced by the authenticated principal — a double-submit yields ONE publisher root; two different principals using the same key get distinct publishers." }, "required": false, "description": "Optional opaque token to deduplicate retries of publisher creation. Namespaced by the authenticated principal — a double-submit yields ONE publisher root; two different principals using the same key get distinct publishers.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 1, "maxLength": 512 }, "registered_country": { "type": "string", "minLength": 2, "maxLength": 2 }, "contact_email": { "type": "string", "maxLength": 320, "format": "email" }, "tax_id": { "type": "string", "minLength": 1, "maxLength": 64 }, "tax_id_kind": { "type": "string", "enum": [ "eu_vat", "pl_nip", "other" ] } }, "required": [ "legal_name", "registered_country", "contact_email", "tax_id", "tax_id_kind" ] } } } }, "responses": { "201": { "description": "Publisher created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "trust_tier": { "type": "string" }, "legal_name": { "type": "string" }, "registered_country": { "type": "string" }, "contact_email": { "type": "string" }, "tax_id": { "type": "string" }, "tax_id_kind": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "trust_tier", "legal_name", "registered_country", "contact_email", "tax_id", "tax_id_kind", "created_at", "updated_at" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found (feature disabled)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid tax id / field", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}": { "get": { "tags": [ "Publishers" ], "summary": "Get own publisher account", "operationId": "getPublisher", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Publisher", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "trust_tier": { "type": "string" }, "legal_name": { "type": "string" }, "registered_country": { "type": "string" }, "contact_email": { "type": "string" }, "tax_id": { "type": "string" }, "tax_id_kind": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "trust_tier", "legal_name", "registered_country", "contact_email", "tax_id", "tax_id_kind", "created_at", "updated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / not a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/domains": { "post": { "tags": [ "Publishers" ], "summary": "Issue (or rotate) a DNS-TXT domain-ownership challenge", "operationId": "createPublisherDomain", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "domain" ] } } } }, "responses": { "200": { "description": "Already verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "publisher_id": { "type": "string" }, "domain": { "type": "string" }, "verification_state": { "type": "string" }, "verification_method": { "type": "string" }, "challenge_expires_at": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "challenge": { "type": "object", "properties": { "record_name": { "type": "string" }, "record_type": { "type": "string", "enum": [ "TXT" ] }, "record_value": { "type": "string" }, "instructions": { "type": "string" } }, "required": [ "record_name", "record_type", "record_value", "instructions" ] } }, "required": [ "id", "publisher_id", "domain", "verification_state", "verification_method", "challenge_expires_at", "verified_at", "created_at", "updated_at" ] } } } }, "201": { "description": "Challenge issued/rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "publisher_id": { "type": "string" }, "domain": { "type": "string" }, "verification_state": { "type": "string" }, "verification_method": { "type": "string" }, "challenge_expires_at": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "challenge": { "type": "object", "properties": { "record_name": { "type": "string" }, "record_type": { "type": "string", "enum": [ "TXT" ] }, "record_value": { "type": "string" }, "instructions": { "type": "string" } }, "required": [ "record_name", "record_type", "record_value", "instructions" ] } }, "required": [ "id", "publisher_id", "domain", "verification_state", "verification_method", "challenge_expires_at", "verified_at", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid / rejected domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / not a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/domains/{domainId}/verify": { "post": { "tags": [ "Publishers" ], "summary": "Verify a domain-ownership challenge (resolves DNS TXT)", "operationId": "verifyPublisherDomain", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "domainId", "in": "path" } ], "responses": { "200": { "description": "Verified (or already verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "publisher_id": { "type": "string" }, "domain": { "type": "string" }, "verification_state": { "type": "string" }, "verification_method": { "type": "string" }, "challenge_expires_at": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "challenge": { "type": "object", "properties": { "record_name": { "type": "string" }, "record_type": { "type": "string", "enum": [ "TXT" ] }, "record_value": { "type": "string" }, "instructions": { "type": "string" } }, "required": [ "record_name", "record_type", "record_value", "instructions" ] } }, "required": [ "id", "publisher_id", "domain", "verification_state", "verification_method", "challenge_expires_at", "verified_at", "created_at", "updated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / not a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "Challenge expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Verification failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/dpa/accept": { "post": { "tags": [ "Publishers" ], "summary": "Accept the current Rakomi↔publisher DPA", "operationId": "acceptPublisherDpa", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer" } } } } } }, "responses": { "200": { "description": "DPA accepted (or already accepted)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "publisher_id": { "type": "string" }, "dpa_version": { "type": "integer" }, "content_hash": { "type": "string" }, "accepted_at": { "type": "string" } }, "required": [ "id", "publisher_id", "dpa_version", "content_hash", "accepted_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / not a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "DPA version mismatch", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/vpp/subscribe": { "post": { "tags": [ "Publishers" ], "summary": "Initiate a Verified Publisher Program subscription (Stripe-hosted checkout)", "operationId": "subscribePublisherVpp", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Checkout session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout_url": { "type": "string" } }, "required": [ "checkout_url" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / not a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Billing temporarily unavailable / VPP not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/vpp/reviews": { "post": { "tags": [ "Publishers" ], "summary": "Request a security review of a signed app version (idempotent per signature)", "operationId": "requestPublisherReview", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "app_version_id": { "type": "string", "format": "uuid" } }, "required": [ "app_version_id" ] } } } }, "responses": { "200": { "description": "Existing open review (idempotent)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "app_version_id": { "type": [ "string", "null" ] }, "decision_at": { "type": [ "string", "null" ] }, "requested_at": { "type": "string" }, "denial_reason": { "type": [ "string", "null" ] }, "sensitive_scope_families_granted": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "id", "status", "app_version_id", "decision_at", "requested_at", "denial_reason", "sensitive_scope_families_granted" ] } } } }, "201": { "description": "Review requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "app_version_id": { "type": [ "string", "null" ] }, "decision_at": { "type": [ "string", "null" ] }, "requested_at": { "type": "string" }, "denial_reason": { "type": [ "string", "null" ] }, "sensitive_scope_families_granted": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "id", "status", "app_version_id", "decision_at", "requested_at", "denial_reason", "sensitive_scope_families_granted" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / not a member / version not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Not eligible (no active subscription)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/vpp/status": { "get": { "tags": [ "Publishers" ], "summary": "VPP subscription + review-currency status (reads local state, Stripe-independent)", "operationId": "getPublisherVppStatus", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "VPP status", "content": { "application/json": { "schema": { "type": "object", "properties": { "publisher_id": { "type": "string" }, "trust_tier": { "type": "string" }, "subscription": { "type": [ "object", "null" ], "properties": { "status": { "type": "string" }, "current_period_end": { "type": [ "string", "null" ] }, "review_sla_due_at": { "type": [ "string", "null" ] } }, "required": [ "status", "current_period_end", "review_sla_due_at" ] }, "review_status": { "type": "object", "properties": { "latest_status": { "type": [ "string", "null" ] }, "approved_version_id": { "type": [ "string", "null" ] }, "current_for_latest_version": { "type": "boolean" }, "stale_reason": { "type": [ "string", "null" ] }, "denial_reason": { "type": [ "string", "null" ] } }, "required": [ "latest_status", "approved_version_id", "current_for_latest_version", "stale_reason", "denial_reason" ] } }, "required": [ "publisher_id", "trust_tier", "subscription", "review_status" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / not a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/metrics": { "get": { "tags": [ "Publishers" ], "summary": "Publisher install metrics (counts/aggregates + stale-review badge — no end-user PII)", "description": "Publisher-axis aggregate metrics for the dashboard: live install count, per-app-version install counts, active backing-client (token) count, the pricing-free per-install MAU rollup for the current billing month, a best-effort revenue figure (OMITTED with a closed `revenue_unavailable_reason` key when the billing surface is not wired — never a 500), and a review-currency badge (`review_status`) enriched from the VPP review state so \"N installs on a stale version\" is actionable. `stale_reason` is a STABLE machine key (the UI localizes it), degrading to `no_review_submitted` for a never-reviewed publisher. COUNTS/aggregates ONLY — no enumerable per-end-user row ever crosses to the publisher axis. Cross-publisher id → 404 (never 403).", "operationId": "getPublisherMetrics", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Publisher metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "install_count": { "type": "integer" }, "per_version_install_counts": { "type": "array", "items": { "type": "object", "properties": { "app_version_id": { "type": "string" }, "install_count": { "type": "integer" } }, "required": [ "app_version_id", "install_count" ] } }, "active_token_count": { "type": "integer" }, "mau_rollup": { "type": "array", "items": { "type": "object", "properties": { "installation_id": { "type": "string" }, "period_month": { "type": "string" }, "mau_count": { "type": "integer" } }, "required": [ "installation_id", "period_month", "mau_count" ] } }, "revenue": { "type": "object", "properties": { "amount_minor": { "type": "integer" }, "currency": { "type": "string" }, "as_of": { "type": "string" } }, "required": [ "amount_minor", "currency", "as_of" ] }, "revenue_unavailable_reason": { "type": "string" }, "review_status": { "type": "object", "properties": { "current_for_latest_version": { "type": "boolean" }, "approved_version_id": { "type": [ "string", "null" ] }, "stale_reason": { "type": [ "string", "null" ] } }, "required": [ "current_for_latest_version", "approved_version_id", "stale_reason" ] }, "as_of": { "type": "string" }, "generated_at": { "type": "string" } }, "required": [ "install_count", "per_version_install_counts", "active_token_count", "mau_rollup", "review_status", "as_of", "generated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / not a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/webhooks": { "post": { "tags": [ "Publishers" ], "summary": "Register a publisher webhook endpoint", "operationId": "createPublisherWebhook", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "description": { "type": "string", "maxLength": 2048 }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "maxItems": 100 } }, "required": [ "name", "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Webhook created (reveal-once secret)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "signing_secret_prefix": { "type": "string" }, "circuit_breaker_status": { "type": "string" }, "consecutive_failures": { "type": "integer" }, "auto_disabled_reason": { "type": [ "string", "null" ] }, "auto_disabled_at": { "type": [ "string", "null" ] }, "test_webhook_url": { "type": [ "string", "null" ] }, "health_badge": { "type": "string", "enum": [ "active", "disabled_manual", "disabled_auto", "circuit_open", "no_data_yet" ] }, "last_delivery_at": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "signing_secret": { "type": "string", "example": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx" } }, "required": [ "id", "name", "url", "description", "status", "event_types", "signing_secret_prefix", "circuit_breaker_status", "consecutive_failures", "auto_disabled_reason", "auto_disabled_at", "test_webhook_url", "health_badge", "created_at", "updated_at", "signing_secret" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found (feature disabled / not a member)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "URL or name collision", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid url / not-subscribable event type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Publishers" ], "summary": "List publisher webhook endpoints + health", "operationId": "listPublisherWebhooks", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "signing_secret_prefix": { "type": "string" }, "circuit_breaker_status": { "type": "string" }, "consecutive_failures": { "type": "integer" }, "auto_disabled_reason": { "type": [ "string", "null" ] }, "auto_disabled_at": { "type": [ "string", "null" ] }, "test_webhook_url": { "type": [ "string", "null" ] }, "health_badge": { "type": "string", "enum": [ "active", "disabled_manual", "disabled_auto", "circuit_open", "no_data_yet" ] }, "last_delivery_at": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "url", "description", "status", "event_types", "signing_secret_prefix", "circuit_breaker_status", "consecutive_failures", "auto_disabled_reason", "auto_disabled_at", "test_webhook_url", "health_badge", "created_at", "updated_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / not a member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Malformed cursor / limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/webhooks/{webhookId}": { "get": { "tags": [ "Publishers" ], "summary": "Get one publisher webhook endpoint + health", "operationId": "getPublisherWebhook", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "webhookId", "in": "path" } ], "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "signing_secret_prefix": { "type": "string" }, "circuit_breaker_status": { "type": "string" }, "consecutive_failures": { "type": "integer" }, "auto_disabled_reason": { "type": [ "string", "null" ] }, "auto_disabled_at": { "type": [ "string", "null" ] }, "test_webhook_url": { "type": [ "string", "null" ] }, "health_badge": { "type": "string", "enum": [ "active", "disabled_manual", "disabled_auto", "circuit_open", "no_data_yet" ] }, "last_delivery_at": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "url", "description", "status", "event_types", "signing_secret_prefix", "circuit_breaker_status", "consecutive_failures", "auto_disabled_reason", "auto_disabled_at", "test_webhook_url", "health_badge", "created_at", "updated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher / deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Publishers" ], "summary": "Update a publisher webhook endpoint", "operationId": "updatePublisherWebhook", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "webhookId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "description": { "type": [ "string", "null" ], "maxLength": 2048 }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "maxItems": 100 }, "test_webhook_url": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "signing_secret_prefix": { "type": "string" }, "circuit_breaker_status": { "type": "string" }, "consecutive_failures": { "type": "integer" }, "auto_disabled_reason": { "type": [ "string", "null" ] }, "auto_disabled_at": { "type": [ "string", "null" ] }, "test_webhook_url": { "type": [ "string", "null" ] }, "health_badge": { "type": "string", "enum": [ "active", "disabled_manual", "disabled_auto", "circuit_open", "no_data_yet" ] }, "last_delivery_at": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "url", "description", "status", "event_types", "signing_secret_prefix", "circuit_breaker_status", "consecutive_failures", "auto_disabled_reason", "auto_disabled_at", "test_webhook_url", "health_badge", "created_at", "updated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher / deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "URL or name collision", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid url / not-subscribable event type / unknown key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Publishers" ], "summary": "Soft-delete a publisher webhook endpoint", "operationId": "deletePublisherWebhook", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "webhookId", "in": "path" } ], "responses": { "204": { "description": "Deleted (empty body)" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher / already deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/webhooks/{webhookId}/rotate": { "post": { "tags": [ "Publishers" ], "summary": "Rotate a publisher webhook signing secret (reveal-once)", "operationId": "rotatePublisherWebhookSecret", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "webhookId", "in": "path" } ], "responses": { "200": { "description": "Rotated (reveal-once secret)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "signing_secret": { "type": "string", "example": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx" }, "signing_secret_prefix": { "type": "string" }, "rotated_at": { "type": "string" } }, "required": [ "id", "signing_secret", "signing_secret_prefix", "rotated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher / deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Rotation cooldown active", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/webhooks/{webhookId}/deliveries": { "get": { "tags": [ "Publishers" ], "summary": "Recent deliveries for a publisher webhook endpoint", "operationId": "listPublisherWebhookDeliveries", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "webhookId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Recent deliveries (empty for an existing endpoint with no deliveries)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "delivery_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string" }, "http_status": { "type": [ "integer", "null" ] }, "response_time_ms": { "type": [ "integer", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "delivered_at": { "type": [ "string", "null" ] }, "last_attempted_at": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "delivery_id", "event_type", "status", "http_status", "response_time_ms", "failure_reason", "attempts", "delivered_at", "last_attempted_at", "scheduled_at", "created_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher / deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Malformed cursor / limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/publishers/{id}/webhooks/{webhookId}/test": { "post": { "tags": [ "Publishers" ], "summary": "Send a single synchronous test delivery to a publisher webhook endpoint", "operationId": "testPublisherWebhook", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "webhookId", "in": "path" } ], "responses": { "200": { "description": "Test delivery result (success:false on a non-2xx target — that is data, not an HTTP error)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "http_status": { "type": [ "integer", "null" ] }, "response_time_ms": { "type": "integer" }, "failure_reason": { "type": [ "string", "null" ] }, "delivery_id": { "type": "string", "format": "uuid" } }, "required": [ "success", "http_status", "response_time_ms", "failure_reason", "delivery_id" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher / deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps": { "post": { "tags": [ "Apps" ], "summary": "Register an app under the acting publisher", "operationId": "createApp", "parameters": [ { "schema": { "type": "string", "maxLength": 255, "description": "Optional opaque token to deduplicate retries of app creation. Namespaced by the acting publisher — a double-submit yields ONE app; publisher B reusing A’s key gets B’s own app." }, "required": false, "description": "Optional opaque token to deduplicate retries of app creation. Namespaced by the acting publisher — a double-submit yields ONE app; publisher B reusing A’s key gets B’s own app.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$" }, "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "slug", "name" ] } } } }, "responses": { "201": { "description": "App created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "publisher_id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "current_version_id": { "type": "string" }, "sunset_at": { "type": "string" }, "sunset_grace_days": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "publisher_id", "slug", "name", "state", "created_at", "updated_at" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found (feature disabled / no publisher)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Slug conflict / ambiguous publisher scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid field", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Apps" ], "summary": "List the acting publisher’s apps", "operationId": "listApps", "parameters": [ { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "App list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "publisher_id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "current_version_id": { "type": "string" }, "sunset_at": { "type": "string" }, "sunset_grace_days": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "publisher_id", "slug", "name", "state", "created_at", "updated_at" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Invalid cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found (feature disabled / no publisher)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{id}": { "get": { "tags": [ "Apps" ], "summary": "Get one of the acting publisher’s apps", "operationId": "getApp", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "App", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "publisher_id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "current_version_id": { "type": "string" }, "sunset_at": { "type": "string" }, "sunset_grace_days": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "publisher_id", "slug", "name", "state", "created_at", "updated_at" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{id}/versions": { "post": { "tags": [ "Apps" ], "summary": "Publish a new immutable, signed manifest version", "operationId": "publishAppVersion", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "semver": { "type": "string", "minLength": 1, "maxLength": 256 }, "manifest": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "type": "string" } }, "webhook_urls": { "type": "array", "items": { "type": "string" } }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "required_aal": { "type": "string", "enum": [ "AAL1", "AAL2" ] } }, "required": [ "scopes" ], "additionalProperties": false } }, "required": [ "semver", "manifest" ] } } } }, "responses": { "201": { "description": "Version published", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "semver": { "type": "string" }, "manifest_hash": { "type": "string" }, "signing_kid": { "type": "string" }, "signature_alg": { "type": "string" }, "published_at": { "type": "string" }, "manifest_json": {}, "manifest_signature": { "type": "string" } }, "required": [ "id", "app_id", "semver", "manifest_hash", "signing_kid", "signature_alg", "published_at", "manifest_signature" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Insufficient trust tier / review attestation expired for a sensitive-scope version", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Version already exists (immutable)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid manifest / semver / scope-change-requires-major", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Manifest signing not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Apps" ], "summary": "List an app’s versions (metadata; omits manifest_json)", "operationId": "listAppVersions", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Version list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "semver": { "type": "string" }, "manifest_hash": { "type": "string" }, "signing_kid": { "type": "string" }, "signature_alg": { "type": "string" }, "published_at": { "type": "string" } }, "required": [ "id", "app_id", "semver", "manifest_hash", "signing_kid", "signature_alg", "published_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{id}/versions/{versionId}": { "get": { "tags": [ "Apps" ], "summary": "Get one version (full manifest + signature for offline verification)", "operationId": "getAppVersion", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "versionId", "in": "path" } ], "responses": { "200": { "description": "Version", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "semver": { "type": "string" }, "manifest_hash": { "type": "string" }, "signing_kid": { "type": "string" }, "signature_alg": { "type": "string" }, "published_at": { "type": "string" }, "manifest_json": {}, "manifest_signature": { "type": "string" } }, "required": [ "id", "app_id", "semver", "manifest_hash", "signing_kid", "signature_alg", "published_at", "manifest_signature" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{id}/transitions": { "post": { "tags": [ "Apps" ], "summary": "Transition an app’s lifecycle state", "operationId": "transitionApp", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "enum": [ "draft", "published", "deprecated", "sunset" ] } }, "required": [ "to" ] } } } }, "responses": { "200": { "description": "Transitioned", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "publisher_id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "current_version_id": { "type": "string" }, "sunset_at": { "type": "string" }, "sunset_grace_days": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "publisher_id", "slug", "name", "state", "created_at", "updated_at" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found / cross-publisher", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid state transition / no published version", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{installationId}/consent": { "post": { "tags": [ "App Installs" ], "summary": "End-user consent → issue a ConsentReceiptCredential", "operationId": "recordAppInstallConsent", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Installation id", "example": "01912345-abcd-7def-8901-234567890abc" }, "required": true, "description": "Installation id", "name": "installationId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ui_locale": { "type": "string", "minLength": 2, "maxLength": 35, "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$", "description": "BCP 47 locale the consent screen rendered in", "example": "pl-PL" } }, "required": [ "ui_locale" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Consent recorded — receipt issued (or idempotent replay)", "content": { "application/json": { "schema": { "type": "object", "properties": { "jti": { "type": "string" }, "vct": { "type": "string" }, "status_list_pointer": { "type": "string" }, "consent_receipt_ref": { "type": "string" } }, "required": [ "jti", "vct", "status_list_pointer", "consent_receipt_ref" ], "additionalProperties": false } } } }, "400": { "description": "Malformed installation id / invalid body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Not authenticated / step-up required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Review attestation expired for a sensitive-scope version", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Install not found / cross-tenant / feature disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Install not active / no approved scopes", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "Receipt issuance temporarily paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "suggested_fix": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } } }, "webhooks": {} }