{ "components": { "schemas": { "access.LoginSession": { "properties": { "account_id": { "type": "string" }, "account_type": { "$ref": "#/components/schemas/account_enums.AccountType" }, "audience": { "type": "string" }, "auth_assurance_level": { "$ref": "#/components/schemas/security_enums.AuthAssuranceLevel" }, "auth_identity_id": { "type": "string" }, "auth_method": { "$ref": "#/components/schemas/security_enums.AuthMethod" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "data_owner_id": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "device_key": { "type": "string" }, "device_name": { "type": "string" }, "device_type": { "$ref": "#/components/schemas/account_enums.DeviceType" }, "expires_at": { "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "identity_domain": { "$ref": "#/components/schemas/security_enums.IdentityDomain" }, "ip_address": { "type": "string" }, "issued_at": { "type": "string" }, "last_seen_at": { "type": "string" }, "legal_hold": { "type": "boolean" }, "mfa_verified_at": { "type": "string" }, "organisation_access_id": { "type": "string" }, "permissions": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "refresh_token_rotated_at": { "type": "string" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "revoked_at": { "type": "string" }, "revoked_reason": { "type": "string" }, "risk_level": { "$ref": "#/components/schemas/security_enums.SecurityRiskLevel" }, "role_key": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "user_agent": { "type": "string" }, "user_id": { "type": "string" }, "wholesale_organisation_code": { "type": "string" } }, "type": "object" }, "access.PortalAccess": { "properties": { "account_id": { "type": "string" }, "account_type": { "$ref": "#/components/schemas/account_enums.AccountType" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "data_owner_id": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "expires_at": { "type": "string" }, "grant": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "id": { "type": "string" }, "legal_hold": { "type": "boolean" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "revocation": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "status": { "$ref": "#/components/schemas/access_enums.PortalAccessStatus" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "access.StaffGeoScope": { "additionalProperties": false, "description": "Workforce geographic authority. GLOBAL has no targets and is reserved for superAdmin. TARGETED has 1 to 100 independent contiguous paths. Every path respects the role's maximum breadth and is checked against Supply before assignment. countryAdmin may target any depth, marketing requires at least market depth, and depot roles require a complete depot path.", "oneOf": [ { "properties": { "mode": { "const": "GLOBAL" }, "targets": { "maxItems": 0 } } }, { "properties": { "mode": { "const": "TARGETED" }, "targets": { "minItems": 1 } }, "required": [ "targets" ] } ], "properties": { "mode": { "enum": [ "GLOBAL", "TARGETED" ], "type": "string" }, "targets": { "items": { "$ref": "#/components/schemas/geography.GeographicPath" }, "maxItems": 100, "type": "array", "uniqueItems": true } }, "required": [ "mode" ], "type": "object" }, "access_enums.PortalAccessStatus": { "enum": [ "pending", "active", "suspended", "revoked" ], "type": "string", "x-enum-varnames": [ "PortalAccessStatusPending", "PortalAccessStatusActive", "PortalAccessStatusSuspended", "PortalAccessStatusRevoked" ] }, "access_enums.ScopeLevel": { "enum": [ "global", "country", "market", "depot" ], "type": "string", "x-enum-varnames": [ "ScopeLevelGlobal", "ScopeLevelCountry", "ScopeLevelMarket", "ScopeLevelDepot" ] }, "account.DeviceIP": { "properties": { "first_seen_at": { "type": "string" }, "ip_address": { "type": "string" }, "last_seen_at": { "type": "string" }, "seen_count": { "type": "integer" } }, "type": "object" }, "account.UserAccount": { "properties": { "account_type": { "$ref": "#/components/schemas/account_enums.AccountType" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "closed_at": { "type": "string" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "data_owner_id": { "type": "string" }, "default_portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "display_name": { "type": "string" }, "id": { "type": "string" }, "last_accessed_at": { "type": "string" }, "legal_hold": { "type": "boolean" }, "primary_email": { "type": "string" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "status": { "$ref": "#/components/schemas/account_enums.AccountStatus" }, "suspended_at": { "type": "string" }, "suspended_reason": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "account.UserAccountSummary": { "properties": { "account_type": { "$ref": "#/components/schemas/account_enums.AccountType" }, "allowed_portals": { "items": { "$ref": "#/components/schemas/identity_enums.Portal" }, "type": "array", "uniqueItems": false }, "display_name": { "type": "string" }, "id": { "type": "string" }, "primary_email": { "type": "string" }, "status": { "$ref": "#/components/schemas/account_enums.AccountStatus" }, "user_id": { "type": "string" } }, "type": "object" }, "account.UserDevice": { "description": "User Operations", "properties": { "browser": { "type": "string" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "data_owner_id": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "device_key": { "type": "string" }, "device_name": { "type": "string" }, "device_type": { "$ref": "#/components/schemas/account_enums.DeviceType" }, "first_seen_at": { "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "ip_address": { "type": "string" }, "ip_history": { "items": { "$ref": "#/components/schemas/account.DeviceIP" }, "type": "array", "uniqueItems": false }, "last_login_at": { "type": "string" }, "last_login_ip": { "type": "string" }, "last_risk_reviewed_at": { "type": "string" }, "last_seen_at": { "type": "string" }, "legal_hold": { "type": "boolean" }, "os": { "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "preferred_language": { "$ref": "#/components/schemas/account_enums.UserPreferredLanguage" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "revoked_at": { "type": "string" }, "revoked_reason": { "type": "string" }, "risk_level": { "$ref": "#/components/schemas/security_enums.SecurityRiskLevel" }, "trust_reason": { "type": "string" }, "trusted": { "type": "boolean" }, "user_agent": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "account.UserDeviceSeenEvent": { "properties": { "device_key": { "type": "string" }, "ip_address": { "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "request_id": { "type": "string" }, "seen_at": { "type": "string" }, "session_id": { "type": "string" }, "user_agent": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "account.UserProfile": { "properties": { "access_reviewed_at": { "type": "string" }, "accounts": { "items": { "$ref": "#/components/schemas/account.UserAccountSummary" }, "type": "array", "uniqueItems": false }, "active": { "type": "boolean" }, "avatar": { "$ref": "#/components/schemas/security.ObjectMedia" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "data_owner_id": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "display_name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "employee_id": { "description": "Identity-assigned immutable eight-digit workforce employee ID. Leading zeros are significant; absent for customers.", "maxLength": 8, "minLength": 8, "pattern": "^[0-9]{8}$", "readOnly": true, "type": "string" }, "geo_scope": { "$ref": "#/components/schemas/access.StaffGeoScope" }, "id": { "type": "string" }, "last_login_at": { "type": "string" }, "legal_hold": { "type": "boolean" }, "mfa_enabled": { "type": "boolean" }, "password_changed_at": { "type": "string" }, "phone": { "pattern": "^\\+[1-9][0-9]{7,14}$", "type": "string" }, "phone_verified_at": { "description": "Absent until the current phone is verified. Cleared when the phone changes.", "format": "date-time", "type": "string" }, "primary_account_id": { "type": "string" }, "primary_account_type": { "$ref": "#/components/schemas/account_enums.AccountType" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "user_device": { "$ref": "#/components/schemas/account.UserDevice" } }, "type": "object" }, "account_enums.AccountStatus": { "enum": [ "pending", "active", "suspended", "closed", "deleted" ], "type": "string", "x-enum-varnames": [ "AccountStatusPending", "AccountStatusActive", "AccountStatusSuspended", "AccountStatusClosed", "AccountStatusDeleted" ] }, "account_enums.AccountType": { "enum": [ "adminUser", "retailCustomer", "wholesaleCustomer" ], "type": "string", "x-enum-varnames": [ "AccountTypeAdminUser", "AccountTypeRetailCustomer", "AccountTypeWholesaleCustomer" ] }, "account_enums.DeviceType": { "enum": [ "desktop", "mobile", "tablet", "api" ], "type": "string", "x-enum-varnames": [ "DeviceTypeDesktop", "DeviceTypeMobile", "DeviceTypeTablet", "DeviceTypeAPI" ] }, "account_enums.UserPreferredLanguage": { "description": "PreferredLanguage is typed as the contract enum\n(account_enums.UserPreferredLanguage) and validated against it; the contract\naccount.UserProfile carries no such field yet, so the value lives\nonly on the stored record until the contract grows one.", "enum": [ "english", "traditional_chinese", "simplified_chinese" ], "type": "string", "x-enum-varnames": [ "PreferredLanguageEnglish", "PreferredLanguageTraditionalChinese", "PreferredLanguageSimplifiedChinese" ] }, "audit.LifecycleAction": { "properties": { "at": { "type": "string" }, "by": { "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "authorisation.RoleAssignment": { "properties": { "account_id": { "type": "string" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "data_owner_id": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "expires_at": { "type": "string" }, "grant": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "id": { "type": "string" }, "legal_hold": { "type": "boolean" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "revocation": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "role_key": { "type": "string" }, "scope_id": { "type": "string" }, "scope_type": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "geography.GeographicPath": { "additionalProperties": false, "description": "Contiguous country to market to official state to depot; operational regions are separate.", "properties": { "country_code": { "pattern": "^[A-Z]{2}$", "type": "string" }, "depot_code": { "maxLength": 128, "minLength": 1, "type": "string" }, "market_code": { "maxLength": 128, "minLength": 1, "type": "string" }, "state_code": { "minLength": 1, "type": "string" } }, "required": [ "country_code" ], "type": "object" }, "github_com_Potato-Mart_Backend-Identity_internal_modules_users.RetailLinkageInspection": { "properties": { "account_id": { "type": "string" }, "account_status": { "$ref": "#/components/schemas/account_enums.AccountStatus" }, "active_customer_identity_count": { "type": "integer" }, "portal_access_found": { "type": "boolean" }, "portal_access_owned": { "description": "Admission belongs to this user and retail account with the retail type and portal.", "type": "boolean" }, "portal_access_status": { "$ref": "#/components/schemas/access_enums.PortalAccessStatus" }, "portal_access_unrestricted": { "description": "Raw admission is active with no revocation or expiry; ownership is reported separately.", "type": "boolean" }, "requested_account_matches": { "type": "boolean" }, "requested_primary_identity_active": { "type": "boolean" }, "requested_primary_identity_found": { "type": "boolean" }, "requested_primary_identity_owned": { "type": "boolean" }, "suggested_primary_auth_identity_id": { "type": "string" }, "suggested_primary_unambiguous": { "type": "boolean" }, "user_active": { "type": "boolean" }, "user_found": { "type": "boolean" }, "user_id": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Identity_internal_modules_users.RetailLinkageSubject": { "properties": { "account_id": { "type": "string" }, "primary_auth_identity_id": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Identity_internal_platform_apiresponse.Error": { "properties": { "code": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_apiresponse_apiresponse_enums.Code" }, "details": { "additionalProperties": { "type": "string" }, "type": "object" }, "message": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Identity_internal_platform_apiresponse_apiresponse_enums.Code": { "enum": [ "INTERNAL_ERROR", "BAD_REQUEST", "VALIDATION_ERROR", "NOT_FOUND", "CONFLICT", "UNAUTHORIZED", "FORBIDDEN", "TOO_MANY_REQUESTS", "REQUEST_BODY_TOO_LARGE", "SERVICE_UNAVAILABLE", "AUTH_INVALID_CREDENTIALS", "AUTH_INVALID_TOKEN", "AUTH_EXPIRED_TOKEN", "AUTH_WRONG_PORTAL", "AUTH_ACCOUNT_DISABLED", "AUTH_MFA_REQUIRED", "AUTH_REAUTH_REQUIRED", "EMAIL_VERIFICATION_REQUIRED", "PHONE_VERIFICATION_REQUIRED", "SECURITY_POLICY_VIOLATION", "IDENTITY_ACCOUNT_TYPE_NOT_ALLOWED", "IDENTITY_PORTAL_ACCESS_DENIED", "IDENTITY_PORTAL_ACCESS_REVOKED", "IDENTITY_ACCOUNT_SUSPENDED", "IDENTITY_AUTH_IDENTITY_DISABLED", "IDENTITY_MFA_REQUIRED", "IDENTITY_WHOLESALE_ORGANISATION_NOT_APPROVED", "IDENTITY_ORGANISATION_ACCESS_REQUIRED", "MEMBERSHIP_NOT_FOUND", "MEMBERSHIP_INACTIVE", "MEMBERSHIP_INSUFFICIENT_POINTS", "MEMBERSHIP_REWARD_UNAVAILABLE", "MEMBERSHIP_POINT_RESERVATION_EXPIRED", "USER_EMAIL_TAKEN", "SKU_CODE_TAKEN", "STORAGE_LOCATION_CODE_TAKEN", "PRODUCT_CODE_TAKEN", "STORAGE_MISMATCH", "INSUFFICIENT_STOCK", "ORDER_INVALID_TRANSITION", "ORDER_TERMINAL", "ORDER_EMPTY", "CART_NOT_ACTIVE", "DISCOUNT_NOT_FOUND", "DISCOUNT_INACTIVE", "DISCOUNT_NOT_STARTED", "DISCOUNT_EXPIRED", "DISCOUNT_EXHAUSTED", "DISCOUNT_MIN_NOT_MET", "DISCOUNT_CODE_TAKEN", "DISCOUNT_INAPPLICABLE", "TERMINAL_NOT_CONNECTED", "TERMINAL_NOT_REGISTERED", "TERMINAL_OUTCOME_UNKNOWN", "TERMINAL_SIGNATURE_FAIL", "TERMINAL_TIMEOUT", "TERMINAL_REQUEST_REJECTED", "TERMINAL_BUSY" ], "type": "string", "x-enum-varnames": [ "CodeInternal", "CodeBadRequest", "CodeValidation", "CodeNotFound", "CodeConflict", "CodeUnauthorized", "CodeForbidden", "CodeTooManyRequests", "CodeRequestTooLarge", "CodeServiceUnavailable", "CodeAuthInvalidCredentials", "CodeAuthInvalidToken", "CodeAuthExpiredToken", "CodeAuthWrongPortal", "CodeAuthAccountDisabled", "CodeAuthMFARequired", "CodeAuthReauthRequired", "CodeEmailVerificationRequired", "CodeSecurityPolicyViolation", "CodeIdentityAccountTypeNotAllowed", "CodeIdentityPortalAccessDenied", "CodeIdentityPortalAccessRevoked", "CodeIdentityAccountSuspended", "CodeIdentityAuthIdentityDisabled", "CodeIdentityMFARequired", "CodeIdentityWholesaleOrganisationNotApproved", "CodeIdentityOrganisationAccessRequired", "CodeMembershipNotFound", "CodeMembershipInactive", "CodeMembershipInsufficientPoints", "CodeMembershipRewardUnavailable", "CodeMembershipPointReservationExpired", "CodeUserEmailTaken", "CodeSKUCodeTaken", "CodeStorageLocationCodeTaken", "CodeProductCodeTaken", "CodeStorageMismatch", "CodeInsufficientStock", "CodeOrderInvalidTransition", "CodeOrderTerminal", "CodeOrderEmpty", "CodeCartNotActive", "CodeDiscountNotFound", "CodeDiscountInactive", "CodeDiscountNotStarted", "CodeDiscountExpired", "CodeDiscountExhausted", "CodeDiscountMinNotMet", "CodeDiscountCodeTaken", "CodeDiscountInapplicable", "CodeTerminalNotConnected", "CodeTerminalNotRegistered", "CodeTerminalOutcomeUnknown", "CodeTerminalSignatureFail", "CodeTerminalTimeout", "CodeTerminalRequestRejected", "CodeTerminalBusy" ] }, "github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse": { "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Identity_internal_platform_paging.PageResponse": { "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total_items": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "identity_enums.Portal": { "enum": [ "control", "retail", "wholesale" ], "type": "string", "x-enum-varnames": [ "PortalControl", "PortalRetail", "PortalWholesale" ] }, "internal_modules_authn.CreateWholesaleUserRequest": { "properties": { "display_name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "password_hash": { "type": "string" } }, "required": [ "email", "password_hash" ], "type": "object" }, "internal_modules_authn.CustomerLookupResponse": { "properties": { "active": { "type": "boolean" }, "display_name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "id": { "type": "string" }, "identity_domain": { "$ref": "#/components/schemas/security_enums.IdentityDomain" } }, "type": "object" }, "internal_modules_authn.DeviceBindingRequest": { "additionalProperties": false, "properties": { "device_key": { "maxLength": 128, "minLength": 16, "pattern": "^[A-Za-z0-9._:-]{16,128}$", "type": "string" }, "session_id": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "user_id", "session_id", "device_key" ], "type": "object" }, "internal_modules_authn.DeviceBindingResponse": { "properties": { "active": { "type": "boolean" } }, "required": [ "active" ], "type": "object" }, "internal_modules_authn.GrantRoleRequest": { "properties": { "assignment": { "$ref": "#/components/schemas/authorisation.RoleAssignment" } }, "required": [ "assignment" ], "type": "object" }, "internal_modules_authn.GrantRoleResponse": { "properties": { "existed": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.HasPasswordIdentityResponse": { "properties": { "has_password_identity": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.InternalUserResponse": { "properties": { "active": { "type": "boolean" }, "display_name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "id": { "type": "string" }, "identity_domain": { "$ref": "#/components/schemas/security_enums.IdentityDomain" }, "pending_phone": { "description": "A number the customer is changing to, awaiting its SMS code. It is not the account's phone; Backend-Notification may text the code to it.", "pattern": "^\\+[1-9][0-9]{7,14}$", "type": "string" }, "phone": { "pattern": "^\\+[1-9][0-9]{7,14}$", "type": "string" }, "phone_verified_at": { "description": "Absent until the current phone is verified. Cleared when the phone changes.", "format": "date-time", "type": "string" }, "preferred_language": { "$ref": "#/components/schemas/account_enums.UserPreferredLanguage" } }, "type": "object" }, "internal_modules_authn.LoginSessionResponse": { "allOf": [ { "$ref": "#/components/schemas/access.LoginSession" }, { "properties": { "current": { "description": "True only for the session identified by the verified caller's access-token claims. Computed for this response and never persisted.", "readOnly": true, "type": "boolean" } }, "required": [ "current" ], "type": "object" } ] }, "internal_modules_authn.OfflineCredential": { "additionalProperties": false, "properties": { "display_name": { "type": "string" }, "employee_id": { "pattern": "^[0-9]{8}$", "type": "string" }, "expires_at": { "description": "Offline start deadline; continued sign-in during the same outage may extend past this time.", "format": "date-time", "type": "string" }, "issued_at": { "format": "date-time", "type": "string" }, "permissions": { "items": { "type": "string" }, "type": "array" }, "revision": { "minimum": 1, "type": "integer" }, "role": { "type": "string" }, "user_id": { "type": "string" }, "verifier": { "additionalProperties": false, "properties": { "algorithm": { "enum": [ "argon2id" ], "type": "string" }, "hash_base64": { "type": "string" }, "iterations": { "minimum": 2, "type": "integer" }, "memory_kib": { "minimum": 16384, "type": "integer" }, "parallelism": { "minimum": 1, "type": "integer" }, "salt_base64": { "type": "string" } }, "required": [ "algorithm", "salt_base64", "memory_kib", "iterations", "parallelism", "hash_base64" ], "type": "object" } }, "required": [ "employee_id", "user_id", "display_name", "role", "permissions", "verifier", "issued_at", "expires_at", "revision" ], "type": "object" }, "internal_modules_authn.OfflinePINRevocationsResponse": { "properties": { "data": { "additionalProperties": false, "properties": { "credentials": { "items": { "additionalProperties": false, "properties": { "revision": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "user_id": { "type": "string" }, "valid": { "type": "boolean" } }, "required": [ "user_id", "revision", "valid" ], "type": "object" }, "maxItems": 10000, "type": "array" }, "generated_at": { "format": "date-time", "type": "string" } }, "required": [ "credentials", "generated_at" ], "type": "object" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_authn.PINLoginPolicyStatus": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "internal_modules_authn.PINRevealResult": { "additionalProperties": false, "properties": { "pin": { "description": "The caller's own PIN, returned only on explicit reveal. Never persist or log this value.", "maxLength": 6, "minLength": 6, "pattern": "^[0-9]{6}$", "readOnly": true, "type": "string" } }, "required": [ "pin" ], "type": "object" }, "internal_modules_authn.PINStatus": { "additionalProperties": false, "properties": { "pin_changed_at": { "description": "UTC timestamp of the latest PIN change, when available.", "format": "date-time", "type": "string" }, "pin_enabled": { "description": "Whether the caller has configured a PIN.", "type": "boolean" }, "pin_locked": { "description": "Whether PIN login is locked; password-authorized replacement or removal clears the lock.", "type": "boolean" } }, "required": [ "pin_enabled", "pin_locked" ], "type": "object" }, "internal_modules_authn.PhoneChallenge": { "additionalProperties": false, "properties": { "code_expires_at": { "description": "Absent when no code was sent.", "format": "date-time", "type": "string" }, "phone": { "description": "The number being verified, or the verified phone when it was posted again.", "type": "string" }, "phone_verified": { "description": "True only when the posted number is already the verified phone; no code was sent.", "type": "boolean" } }, "required": [ "phone", "phone_verified" ], "type": "object" }, "internal_modules_authn.PhoneChallengeResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.PhoneChallenge" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_authn.PhoneConfirmRequest": { "additionalProperties": false, "properties": { "code": { "maxLength": 6, "minLength": 6, "pattern": "^[0-9]{6}$", "type": "string" } }, "required": [ "code" ], "type": "object" }, "internal_modules_authn.PhoneRequest": { "additionalProperties": false, "properties": { "locale": { "enum": [ "en", "zh-TW", "zh-CN" ], "type": "string" }, "phone_e164": { "pattern": "^\\+[1-9][0-9]{7,14}$", "type": "string" } }, "required": [ "phone_e164" ], "type": "object" }, "internal_modules_authn.ProvisionAccountRequest": { "properties": { "account_type": { "$ref": "#/components/schemas/account_enums.AccountType" }, "actor": { "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "user_id": { "type": "string" } }, "required": [ "account_type", "portal", "user_id" ], "type": "object" }, "internal_modules_authn.ProvisionAccountResponse": { "properties": { "account": { "$ref": "#/components/schemas/account.UserAccount" }, "existed": { "type": "boolean" }, "portal_access": { "$ref": "#/components/schemas/access.PortalAccess" } }, "type": "object" }, "internal_modules_authn.ProvisionWholesaleAccountRequest": { "properties": { "actor": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "user_id" ], "type": "object" }, "internal_modules_authn.ProvisionWholesaleAccountResponse": { "properties": { "account_id": { "type": "string" } }, "type": "object" }, "internal_modules_authn.RetailLinkageInspectionRequest": { "properties": { "subjects": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_modules_users.RetailLinkageSubject" }, "maxItems": 200, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "subjects" ], "type": "object" }, "internal_modules_authn.RetailLinkageInspectionResponse": { "properties": { "subjects": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_modules_users.RetailLinkageInspection" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_authn.RevokePortalRequest": { "properties": { "account_id": { "type": "string" }, "actor": { "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "reason": { "type": "string" } }, "required": [ "account_id", "portal" ], "type": "object" }, "internal_modules_authn.RevokeRoleRequest": { "properties": { "account_id": { "type": "string" }, "actor": { "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "reason": { "type": "string" }, "role_key": { "type": "string" }, "scope_id": { "type": "string" }, "scope_type": { "type": "string" } }, "required": [ "account_id", "portal", "role_key" ], "type": "object" }, "internal_modules_authn.SessionIntrospectRequest": { "properties": { "session_id": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "session_id", "user_id" ], "type": "object" }, "internal_modules_authn.SessionIntrospectResponse": { "properties": { "access_mode": { "enum": [ "full", "restricted" ], "type": "string" }, "active": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.TokenPair": { "properties": { "access_token": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "token_type": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "expires_at", "refresh_token" ], "type": "object" }, "internal_modules_authn.UserLookupRequest": { "properties": { "user_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "required": [ "user_ids" ], "type": "object" }, "internal_modules_authn.UserLookupResponse": { "properties": { "users": { "additionalProperties": { "$ref": "#/components/schemas/account.UserProfile" }, "type": "object" } }, "type": "object" }, "internal_modules_authn.VerifyPasswordResult": { "properties": { "verified": { "const": true, "type": "boolean" } }, "required": [ "verified" ], "type": "object" }, "internal_modules_authn.WholesaleRegistrationRequest": { "properties": { "display_name": { "type": "string" }, "email": { "type": "string" }, "locale": { "type": "string" }, "password": { "type": "string" } }, "required": [ "email", "password" ], "type": "object" }, "internal_modules_authn.WholesaleRegistrationResponse": { "allOf": [ { "$ref": "#/components/schemas/account.UserProfile" }, { "properties": { "created_user": { "description": "True only when this request created the identity; false when an existing password identity was reused and provisioned for wholesale access.", "type": "boolean" } }, "required": [ "created_user" ], "type": "object" } ] }, "internal_modules_authn.WholesaleVerificationRequest": { "properties": { "email": { "type": "string" }, "locale": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "email", "user_id" ], "type": "object" }, "internal_modules_authn.customerLookupAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.CustomerLookupResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.deviceBindingAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.DeviceBindingResponse" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_authn.forgotPasswordReq": { "properties": { "email": { "type": "string" }, "locale": { "enum": [ "en", "zh-TW", "zh-CN" ], "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal", "description": "Required identity portal; Events uses wholesale." }, "storefront_code": { "description": "Optional owned email destination. Only events is supported and requires portal wholesale. Omit to retain existing reset email routing; callback URLs are not accepted.", "enum": [ "events" ], "type": "string" } }, "required": [ "email", "portal" ], "type": "object" }, "internal_modules_authn.grantRoleAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.GrantRoleResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.hasPasswordIdentityAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.HasPasswordIdentityResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.internalUserProfileAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.InternalUserResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.loginReq": { "properties": { "browser": { "type": "string" }, "device_key": { "type": "string" }, "device_name": { "type": "string" }, "device_type": { "$ref": "#/components/schemas/account_enums.DeviceType" }, "email": { "type": "string" }, "os": { "type": "string" }, "password": { "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" } }, "required": [ "device_key", "email", "password", "portal" ], "type": "object" }, "internal_modules_authn.loginSessionListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/internal_modules_authn.LoginSessionResponse" }, "type": "array", "uniqueItems": false }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.logoutReq": { "properties": { "refresh_token": { "type": "string" } }, "type": "object" }, "internal_modules_authn.passwordReauthenticationResponse": { "properties": { "data": { "properties": { "tokens": { "properties": { "access_token": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "description": "Included in body transport; omitted when sent in the HttpOnly refresh cookie.", "type": "string" }, "token_type": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "expires_at" ], "type": "object" }, "user": { "$ref": "#/components/schemas/account.UserProfile" } }, "required": [ "tokens", "user" ], "type": "object" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_authn.pinLoginPolicyResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.PINLoginPolicyStatus" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_authn.pinLoginReq": { "additionalProperties": false, "properties": { "device_key": { "description": "Existing stable client installation identifier, normalized and validated as 16-128 safe identifier characters.", "type": "string" }, "employee_id": { "description": "Exact eight-digit employee ID, whether typed or read from its barcode. Leading zeros are preserved.", "maxLength": 8, "minLength": 8, "pattern": "^[0-9]{8}$", "type": "string" }, "offline_credential_request": { "additionalProperties": false, "properties": { "device_salt_base64": { "description": "Canonical padded base64 encoding of a 16-to-32-byte device salt.", "type": "string" } }, "required": [ "device_salt_base64" ], "type": "object" }, "pin": { "format": "password", "maxLength": 6, "minLength": 6, "pattern": "^[0-9]{6}$", "type": "string", "writeOnly": true } }, "required": [ "employee_id", "pin", "device_key" ], "type": "object" }, "internal_modules_authn.pinLoginResponse": { "properties": { "data": { "properties": { "offline_credential": { "$ref": "#/components/schemas/internal_modules_authn.OfflineCredential" }, "tokens": { "properties": { "access_token": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "token_type": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "expires_at" ], "type": "object" }, "user": { "$ref": "#/components/schemas/account.UserProfile" } }, "required": [ "tokens", "user" ], "type": "object" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_authn.pinRevealResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.PINRevealResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_authn.pinStatusResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.PINStatus" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_authn.posAccessErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.posAccessResponse": { "properties": { "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.provisionAccountAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.ProvisionAccountResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.provisionWholesaleAccountAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.ProvisionWholesaleAccountResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.referralCheckData": { "additionalProperties": false, "properties": { "valid": { "type": "boolean" } }, "required": [ "valid" ], "type": "object" }, "internal_modules_authn.referralCheckReq": { "additionalProperties": false, "properties": { "code": { "description": "Referral code; trimmed and normalized to uppercase. Blank after trimming is invalid.", "minLength": 1, "type": "string" } }, "required": [ "code" ], "type": "object" }, "internal_modules_authn.referralCheckResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.referralCheckData" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_authn.refreshReq": { "properties": { "browser": { "type": "string" }, "device_key": { "type": "string" }, "device_name": { "type": "string" }, "device_type": { "$ref": "#/components/schemas/account_enums.DeviceType" }, "os": { "type": "string" }, "refresh_token": { "type": "string" } }, "required": [ "device_key", "refresh_token" ], "type": "object" }, "internal_modules_authn.registerReq": { "additionalProperties": false, "properties": { "display_name": { "type": "string" }, "email": { "type": "string" }, "locale": { "enum": [ "en", "zh-TW", "zh-CN" ], "type": "string" }, "password": { "minLength": 10, "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "referral_code": { "description": "Optional; trimmed and normalized to uppercase. Nonblank codes are checked before account mutations.", "type": "string" } }, "required": [ "email", "password" ], "type": "object" }, "internal_modules_authn.removePINRequest": { "additionalProperties": false, "properties": { "current_password": { "format": "password", "minLength": 1, "type": "string", "writeOnly": true } }, "required": [ "current_password" ], "type": "object" }, "internal_modules_authn.resendVerificationReq": { "properties": { "email": { "type": "string" }, "locale": { "enum": [ "en", "zh-TW", "zh-CN" ], "type": "string" }, "portal": { "$ref": "#/components/schemas/internal_modules_authn.verificationPortal", "default": "retail" } }, "required": [ "email", "portal" ], "type": "object" }, "internal_modules_authn.resetPasswordReq": { "properties": { "new_password": { "description": "At least 10 Unicode codepoints and at most 72 UTF-8 bytes. Byte length is validated separately from the JSON Schema character limit. Invalid length returns VALIDATION_ERROR before consuming the token.", "maxLength": 72, "minLength": 10, "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "token": { "type": "string" } }, "required": [ "new_password", "portal", "token" ], "type": "object" }, "internal_modules_authn.retailLinkageInspectionAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.RetailLinkageInspectionResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.sessionIntrospectAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.SessionIntrospectResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.setPINLoginPolicyReq": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "internal_modules_authn.setPINRequest": { "additionalProperties": false, "properties": { "current_password": { "format": "password", "minLength": 1, "type": "string", "writeOnly": true }, "new_pin": { "description": "Exactly six ASCII digits, including leading zeros. The old PIN is not required.", "format": "password", "maxLength": 6, "minLength": 6, "pattern": "^[0-9]{6}$", "type": "string", "writeOnly": true } }, "required": [ "current_password", "new_pin" ], "type": "object" }, "internal_modules_authn.userLookupAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.UserLookupResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.userProfileAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/account.UserProfile" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_authn.verificationPortal": { "enum": [ "retail", "wholesale" ], "type": "string", "x-enum-varnames": [ "verificationPortalRetail", "verificationPortalWholesale" ] }, "internal_modules_authn.verifyEmailReq": { "properties": { "code": { "maxLength": 6, "minLength": 6, "pattern": "^[0-9]{6}$", "type": "string" }, "email": { "type": "string" }, "portal": { "$ref": "#/components/schemas/internal_modules_authn.verificationPortal" } }, "required": [ "code", "email", "portal" ], "type": "object" }, "internal_modules_authn.verifyPasswordFailureError": { "properties": { "code": { "enum": [ "AUTH_PASSWORD_VERIFICATION_FAILED" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "internal_modules_authn.verifyPasswordFailureResponse": { "properties": { "error": { "$ref": "#/components/schemas/internal_modules_authn.verifyPasswordFailureError" }, "success": { "const": false, "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" }, "internal_modules_authn.verifyPasswordReq": { "properties": { "password": { "format": "password", "minLength": 1, "type": "string", "writeOnly": true } }, "required": [ "password" ], "type": "object" }, "internal_modules_authn.verifyPasswordResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.VerifyPasswordResult" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_apiresponse.Error" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_authn.wholesaleRegistrationAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_authn.WholesaleRegistrationResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_devices.PortalDeviceTypeCount": { "properties": { "count": { "type": "integer" }, "device_type": { "type": "string" }, "portal": { "type": "string" } }, "type": "object" }, "internal_modules_devices.RegisterInput": { "properties": { "browser": { "type": "string" }, "device_key": { "type": "string" }, "device_name": { "type": "string" }, "device_type": { "$ref": "#/components/schemas/account_enums.DeviceType" }, "os": { "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "preferred_language": { "$ref": "#/components/schemas/account_enums.UserPreferredLanguage" } }, "required": [ "device_key" ], "type": "object" }, "internal_modules_devices.SeenInput": { "properties": { "device_key": { "type": "string" }, "portal": { "$ref": "#/components/schemas/identity_enums.Portal" }, "session_id": { "type": "string" } }, "type": "object" }, "internal_modules_devices.TrustInput": { "properties": { "trusted": { "type": "boolean" } }, "type": "object" }, "internal_modules_devices.deviceStatsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/internal_modules_devices.PortalDeviceTypeCount" }, "type": "array", "uniqueItems": false }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_devices.userDeviceListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/account.UserDevice" }, "type": "array", "uniqueItems": false }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_devices.userDeviceResponse": { "properties": { "data": { "$ref": "#/components/schemas/account.UserDevice" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_devices.userDeviceSeenResponse": { "properties": { "data": { "$ref": "#/components/schemas/account.UserDeviceSeenEvent" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_erasure.AccessMode": { "enum": [ "full", "restricted" ], "type": "string", "x-enum-varnames": [ "AccessModeFull", "AccessModeRestricted" ] }, "internal_modules_erasure.AdminRequest": { "properties": { "access_mode": { "$ref": "#/components/schemas/internal_modules_erasure.AccessMode" }, "account_id": { "type": "string" }, "id": { "type": "string" }, "local_receipt": { "$ref": "#/components/schemas/internal_modules_erasure.LocalReceipt" }, "peer_operations": { "items": { "$ref": "#/components/schemas/internal_modules_erasure.PeerOperation" }, "type": "array", "uniqueItems": false }, "requested_at": { "type": "string" }, "review_reason": { "type": "string" }, "reviewed_at": { "type": "string" }, "reviewed_by": { "type": "string" }, "state": { "$ref": "#/components/schemas/internal_modules_erasure.State" }, "updated_at": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "internal_modules_erasure.CustomerRequest": { "properties": { "access_mode": { "$ref": "#/components/schemas/internal_modules_erasure.AccessMode" }, "id": { "type": "string" }, "requested_at": { "type": "string" }, "state": { "$ref": "#/components/schemas/internal_modules_erasure.State" }, "updated_at": { "type": "string" } }, "type": "object" }, "internal_modules_erasure.LocalReceipt": { "properties": { "action": { "type": "string" }, "description": { "type": "string" }, "recorded_at": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "internal_modules_erasure.PeerOperation": { "properties": { "action": { "type": "string" }, "attempts": { "type": "integer" }, "last_error": { "type": "string" }, "next_attempt_at": { "type": "string" }, "service": { "type": "string" }, "status": { "$ref": "#/components/schemas/internal_modules_erasure.PeerOperationStatus" }, "updated_at": { "type": "string" } }, "type": "object" }, "internal_modules_erasure.PeerOperationStatus": { "enum": [ "pending", "succeeded" ], "type": "string", "x-enum-varnames": [ "PeerOperationPending", "PeerOperationSucceeded" ] }, "internal_modules_erasure.ReviewDecision": { "enum": [ "approve", "action_required" ], "type": "string", "x-enum-varnames": [ "ReviewDecisionApprove", "ReviewDecisionActionRequired" ] }, "internal_modules_erasure.State": { "enum": [ "restricting", "under_review", "action_required", "approved", "executing", "execution_failed", "completed", "cancelling", "cancelled" ], "type": "string", "x-enum-varnames": [ "StateRestricting", "StateUnderReview", "StateActionRequired", "StateApproved", "StateExecuting", "StateExecutionFailed", "StateCompleted", "StateCancelling", "StateCancelled" ] }, "internal_modules_erasure.adminRequestListData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_erasure.AdminRequest" }, "type": "array", "uniqueItems": false }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_paging.PageResponse" } }, "type": "object" }, "internal_modules_erasure.adminRequestListResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_erasure.adminRequestListData" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_erasure.adminRequestResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_erasure.AdminRequest" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_erasure.customerRequestResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_erasure.CustomerRequest" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_erasure.reviewRequest": { "properties": { "decision": { "$ref": "#/components/schemas/internal_modules_erasure.ReviewDecision" }, "reason": { "maxLength": 500, "type": "string" } }, "required": [ "decision" ], "type": "object" }, "internal_modules_federatedauth.CompleteResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/internal_modules_federatedauth.CompleteResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_federatedauth.CompleteResult": { "additionalProperties": false, "properties": { "email_capture_id": { "maxLength": 43, "minLength": 43, "type": "string" }, "email_verification_id": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "grant": { "type": "string" }, "link_confirmation_id": { "description": "A web link waiting for POST /users/me/federated-identities/link-confirmations/complete by the user who started it, with the device it started on. Native links answer linked_identity_id instead.", "maxLength": 43, "minLength": 43, "type": "string" }, "linked_identity_id": { "type": "string" }, "profile": { "$ref": "#/components/schemas/account.UserProfile" }, "tokens": { "$ref": "#/components/schemas/internal_modules_authn.TokenPair" } }, "type": "object" }, "internal_modules_federatedauth.EmailCaptureRequest": { "additionalProperties": false, "properties": { "device_key": { "maxLength": 128, "minLength": 16, "type": "string" }, "email": { "format": "email", "maxLength": 320, "type": "string" }, "email_capture_id": { "maxLength": 43, "minLength": 43, "type": "string" } }, "required": [ "email_capture_id", "device_key", "email" ], "type": "object" }, "internal_modules_federatedauth.FacebookDeletionResult": { "properties": { "confirmation_code": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "internal_modules_federatedauth.LinkConfirmationRequest": { "additionalProperties": false, "properties": { "device_key": { "description": "The device the link started with, read by the storefront server from its HttpOnly device cookie.", "maxLength": 128, "minLength": 16, "type": "string" }, "link_confirmation_id": { "maxLength": 43, "minLength": 43, "type": "string" } }, "required": [ "link_confirmation_id", "device_key" ], "type": "object" }, "internal_modules_federatedauth.Platform": { "enum": [ "web", "ios", "android" ], "type": "string", "x-enum-varnames": [ "PlatformWeb", "PlatformIOS", "PlatformAndroid" ] }, "internal_modules_federatedauth.ProviderAccountLinkedElsewhereResponse": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "enum": [ "CONFLICT" ], "type": "string" }, "details": { "additionalProperties": false, "properties": { "reason": { "enum": [ "provider_account_linked_elsewhere" ], "type": "string" } }, "required": [ "reason" ], "type": "object" }, "message": { "enum": [ "the provider account is linked to another account" ], "type": "string" } }, "required": [ "code", "message", "details" ], "type": "object" }, "success": { "const": false, "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" }, "internal_modules_federatedauth.appleEventRequest": { "properties": { "payload": { "maxLength": 32768, "type": "string" } }, "required": [ "payload" ], "type": "object" }, "internal_modules_federatedauth.completeRequest": { "properties": { "access_token": { "description": "Facebook on ios or android only. The Graph user access token the Facebook SDK returned when it returned no Limited Login ID token (the Android SDK). Identity checks it with Graph debug_token (valid, issued to the configured Meta app, an expiring user token issued after the flow started) and reads /me with appsecret_proof. Send exactly one of code, assertion, and access_token.", "maxLength": 4096, "type": "string" }, "application_id": { "maxLength": 256, "type": "string" }, "assertion": { "maxLength": 32768, "type": "string" }, "browser": { "maxLength": 128, "type": "string" }, "code": { "maxLength": 4096, "type": "string" }, "device_key": { "maxLength": 128, "minLength": 16, "type": "string" }, "device_name": { "maxLength": 256, "type": "string" }, "device_type": { "$ref": "#/components/schemas/account_enums.DeviceType" }, "email": { "maxLength": 320, "type": "string" }, "family_name": { "description": "Apple only. The family name Apple shared on the first authorization; ignored for other providers. Names only an account Identity creates; the display name is cut to 128 characters.", "maxLength": 1024, "type": "string" }, "given_name": { "description": "Apple only. The given name Apple shared on the first authorization; ignored for other providers. Names only an account Identity creates; the display name is cut to 128 characters.", "maxLength": 1024, "type": "string" }, "issuer": { "maxLength": 2048, "type": "string" }, "os": { "maxLength": 128, "type": "string" }, "platform": { "$ref": "#/components/schemas/internal_modules_federatedauth.Platform" }, "state": { "maxLength": 2048, "type": "string" } }, "required": [ "application_id", "device_key", "platform", "state" ], "type": "object" }, "internal_modules_federatedauth.emailVerificationRequest": { "properties": { "code": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "internal_modules_federatedauth.grantExchangeRequest": { "properties": { "device_key": { "description": "The device the flow started with, read by the storefront server from its HttpOnly device cookie.", "maxLength": 128, "minLength": 16, "type": "string" }, "grant": { "maxLength": 2048, "type": "string" } }, "required": [ "grant", "device_key" ], "type": "object" }, "internal_modules_federatedauth.startRequest": { "properties": { "application_id": { "maxLength": 256, "type": "string" }, "browser": { "maxLength": 128, "type": "string" }, "device_key": { "maxLength": 128, "minLength": 16, "type": "string" }, "device_name": { "maxLength": 256, "type": "string" }, "device_type": { "$ref": "#/components/schemas/account_enums.DeviceType" }, "os": { "maxLength": 128, "type": "string" }, "platform": { "$ref": "#/components/schemas/internal_modules_federatedauth.Platform" } }, "required": [ "application_id", "device_key", "platform" ], "type": "object" }, "internal_modules_pushdestinations.RegisterInput": { "properties": { "app_id": { "type": "string" }, "destination": { "type": "string" }, "environment": { "enum": [ "development", "staging", "production" ], "type": "string" }, "platform": { "enum": [ "android", "ios", "web" ], "type": "string" }, "provider": { "type": "string" } }, "required": [ "app_id", "destination", "environment", "platform" ], "type": "object" }, "internal_modules_pushdestinations.Registration": { "properties": { "app_id": { "type": "string" }, "destination_hash": { "type": "string" }, "device_key": { "type": "string" }, "environment": { "type": "string" }, "platform": { "type": "string" }, "provider": { "type": "string" }, "registered_at": { "type": "string" }, "revoked_at": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "internal_modules_pushdestinations.RegistrationAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_pushdestinations.Registration" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_pushdestinations.ResolutionAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_pushdestinations.ResolutionResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_pushdestinations.ResolutionRequest": { "properties": { "app_ids": { "items": { "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array", "uniqueItems": false }, "cursor": { "type": "string" }, "environment": { "enum": [ "development", "staging", "production" ], "type": "string" }, "page_size": { "maximum": 500, "minimum": 1, "type": "integer" }, "user_ids": { "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "app_ids", "environment", "user_ids" ], "type": "object" }, "internal_modules_pushdestinations.ResolutionResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_pushdestinations.ResolvedDestination" }, "type": "array", "uniqueItems": false }, "next_cursor": { "type": "string" } }, "type": "object" }, "internal_modules_pushdestinations.ResolvedDestination": { "properties": { "app_id": { "type": "string" }, "destination": { "type": "string" }, "destination_hash": { "type": "string" }, "device_key": { "type": "string" }, "environment": { "type": "string" }, "platform": { "type": "string" }, "provider": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "internal_modules_pushdestinations.RevocationAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_pushdestinations.RevocationResult" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_pushdestinations.RevocationResult": { "properties": { "revoked": { "format": "int64", "type": "integer" } }, "type": "object" }, "internal_modules_pushdestinations.RevokeRequest": { "properties": { "destination_hashes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "reason": { "type": "string" } }, "required": [ "destination_hashes" ], "type": "object" }, "internal_modules_retailregistration.APIResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/internal_modules_retailregistration.Result" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_retailregistration.CancelInput": { "additionalProperties": false, "properties": { "customer_fence": { "description": "Stable svc-customers attestation that its durable operation is cancelled and all future profile/link commits for this operation are fenced. Replays require the same fence. Not a bearer credential.", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{15,127}$", "type": "string" }, "input": { "$ref": "#/components/schemas/internal_modules_retailregistration.CreateInput" } }, "required": [ "input", "customer_fence" ], "type": "object" }, "internal_modules_retailregistration.ConfirmInput": { "additionalProperties": false, "properties": { "account_id": { "pattern": "^[0-9a-f]{24}$", "type": "string" }, "auth_identity_id": { "pattern": "^[0-9a-f]{24}$", "type": "string" }, "customer_id": { "pattern": "^[0-9a-f]{24}$", "type": "string" }, "customer_number": { "description": "Must equal the committed Customers provider projection; no surrounding whitespace.", "maxLength": 64, "minLength": 1, "type": "string" }, "user_id": { "pattern": "^[0-9a-f]{24}$", "type": "string" } }, "required": [ "user_id", "account_id", "auth_identity_id", "customer_id", "customer_number" ], "type": "object" }, "internal_modules_retailregistration.CreateInput": { "additionalProperties": false, "properties": { "actor_user_id": { "description": "Authenticated workforce actor attested by svc-customers; immutable within this operation.", "pattern": "^[0-9a-f]{24}$", "type": "string" }, "display_name": { "maxLength": 200, "type": "string" }, "email": { "description": "Trimmed and lowercased before ownership reservation; existing identities are never adopted.", "format": "email", "maxLength": 254, "type": "string" }, "locale": { "default": "en", "enum": [ "en", "zh-TW", "zh-CN" ], "type": "string" }, "operation_id": { "description": "Stable caller operation key. Reuse requires the same canonical input and actor.", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{15,127}$", "type": "string" }, "phone": { "description": "Optional unverified contact captured with Customers normalization. Does not require SMS verification or prove ownership.", "pattern": "^\\+[1-9][0-9]{1,14}$", "type": "string" }, "source": { "enum": [ "pos" ], "type": "string" } }, "required": [ "operation_id", "email", "source", "actor_user_id" ], "type": "object" }, "internal_modules_retailregistration.Result": { "additionalProperties": false, "properties": { "account_id": { "type": "string" }, "auth_identity_id": { "type": "string" }, "customer_id": { "type": "string" }, "customer_number": { "type": "string" }, "operation_id": { "type": "string" }, "status": { "enum": [ "provisioned", "confirmed", "claimed", "cancelled" ], "type": "string" }, "user_id": { "type": "string" } }, "required": [ "operation_id", "status" ], "type": "object" }, "internal_modules_roles.setPermissionsReq": { "properties": { "permissions": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "required": [ "permissions" ], "type": "object" }, "internal_modules_security.CloudServiceSecurityProfile": { "properties": { "backup_enabled": { "type": "boolean" }, "compliance_references": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "configuration_baseline": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "customer_managed_keys": { "type": "boolean" }, "data_residency": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "deletion_supported": { "type": "boolean" }, "dlp_enabled": { "type": "boolean" }, "encryption_at_rest": { "type": "boolean" }, "encryption_in_transit": { "type": "boolean" }, "environment": { "description": "\"dev\", \"staging\", \"prod\"", "type": "string" }, "id": { "type": "string" }, "last_config_reviewed_at": { "type": "string" }, "last_risk_reviewed_at": { "type": "string" }, "logging_enabled": { "type": "boolean" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "monitoring_enabled": { "type": "boolean" }, "owner_id": { "type": "string" }, "provider": { "description": "e.g. \"azure\", \"aws\", \"gcp\"", "type": "string" }, "region": { "type": "string" }, "service_name": { "type": "string" }, "supplier_agreement_id": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "internal_modules_security.CustodyInput": { "properties": { "action": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "action" ], "type": "object" }, "internal_modules_security.SecurityPolicySettings": { "properties": { "access_log_retention_days": { "type": "integer" }, "access_token_ttl_seconds": { "type": "integer" }, "audit_log_retention_days": { "type": "integer" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "data_deletion_grace_days": { "type": "integer" }, "data_retention_default_days": { "type": "integer" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "encryption_at_rest_required": { "type": "boolean" }, "encryption_in_transit_required": { "type": "boolean" }, "environment": { "description": "\"dev\", \"staging\", \"prod\"", "type": "string" }, "evidence_retention_days": { "type": "integer" }, "failed_login_lockout_minutes": { "type": "integer" }, "failed_login_lockout_threshold": { "type": "integer" }, "id": { "type": "string" }, "integrity_hash_required_for_audit_log": { "type": "boolean" }, "last_reviewed_at": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "mfa_required_for_admins": { "type": "boolean" }, "mfa_required_for_staff": { "type": "boolean" }, "password_min_length": { "type": "integer" }, "password_require_lowercase": { "type": "boolean" }, "password_require_number": { "type": "boolean" }, "password_require_symbol": { "type": "boolean" }, "password_require_uppercase": { "type": "boolean" }, "pii_export_requires_mfa": { "type": "boolean" }, "privileged_actions_require_reauth": { "type": "boolean" }, "refresh_token_rotation_enabled": { "type": "boolean" }, "refresh_token_ttl_seconds": { "type": "integer" }, "reviewed_by": { "type": "string" }, "security_event_retention_days": { "type": "integer" }, "session_absolute_timeout_minutes": { "type": "integer" }, "session_idle_timeout_minutes": { "type": "integer" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "internal_modules_security.UpdateEventStatusInput": { "properties": { "assigned_to": { "type": "string" }, "resolution": { "type": "string" }, "status": { "$ref": "#/components/schemas/security_enums.SecurityEventStatus" } }, "required": [ "status" ], "type": "object" }, "internal_modules_security.linkEventsReq": { "properties": { "event_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "required": [ "event_ids" ], "type": "object" }, "internal_modules_svctoken.serviceTokenRequest": { "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "client_id", "client_secret" ], "type": "object" }, "internal_modules_users.BulkUpdateInput": { "additionalProperties": false, "properties": { "ids": { "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "patch": { "additionalProperties": false, "properties": { "active": { "type": "boolean" } }, "required": [ "active" ], "type": "object" } }, "required": [ "ids", "patch" ], "type": "object" }, "internal_modules_users.BulkUpdateResponse": { "properties": { "data": { "properties": { "ids": { "items": { "type": "string" }, "type": "array" }, "updated_count": { "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "ids", "updated_count" ], "type": "object" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_users.CreateInput": { "properties": { "display_name": { "type": "string" }, "email": { "type": "string" }, "geo_scope": { "$ref": "#/components/schemas/access.StaffGeoScope" }, "password": { "type": "string" }, "role": { "$ref": "#/components/schemas/role_enums.UserRole" } }, "required": [ "email", "password", "role" ], "type": "object" }, "internal_modules_users.EmailVerificationAudit": { "properties": { "actor_email": { "type": "string" }, "actor_id": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "is_verified": { "type": "boolean" }, "reason": { "type": "string" }, "request_id": { "type": "string" }, "user_id": { "type": "string" }, "verified_at": { "type": "string" }, "was_verified": { "type": "boolean" } }, "type": "object" }, "internal_modules_users.ManualEmailVerificationInput": { "properties": { "reason": { "type": "string" } }, "required": [ "reason" ], "type": "object" }, "internal_modules_users.ManualEmailVerificationResult": { "properties": { "audit": { "$ref": "#/components/schemas/internal_modules_users.EmailVerificationAudit" }, "user": { "$ref": "#/components/schemas/account.UserProfile" } }, "type": "object" }, "internal_modules_users.SelfUpdateInput": { "properties": { "avatar": { "$ref": "#/components/schemas/security.ObjectMedia" }, "display_name": { "type": "string" }, "email": { "description": "Customer email update only. Workforce email is immutable; an unchanged address is accepted for compatibility.", "type": "string" }, "mfa_enabled": { "type": "boolean" }, "preferred_language": { "$ref": "#/components/schemas/account_enums.UserPreferredLanguage" } }, "type": "object" }, "internal_modules_users.UpdateInput": { "properties": { "active": { "type": "boolean" }, "display_name": { "type": "string" }, "geo_scope": { "$ref": "#/components/schemas/access.StaffGeoScope" }, "role": { "$ref": "#/components/schemas/role_enums.UserRole" } }, "type": "object" }, "internal_modules_users.changePasswordReq": { "properties": { "current_password": { "type": "string" }, "new_password": { "minLength": 10, "type": "string" } }, "required": [ "current_password", "new_password" ], "type": "object" }, "internal_modules_users.setPasswordReq": { "properties": { "new_password": { "minLength": 10, "type": "string" } }, "required": [ "new_password" ], "type": "object" }, "internal_modules_users.verifyEmailResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_users.ManualEmailVerificationResult" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" }, "metadata.Metadata": { "additionalProperties": {}, "type": "object" }, "role_enums.UserRole": { "enum": [ "superAdmin", "countryAdmin", "depotManager", "marketing", "warehouseManager", "warehouseOperator" ], "type": "string", "x-enum-varnames": [ "UserRoleSuperAdmin", "UserRoleCountryAdmin", "UserRoleDepotManager", "UserRoleMarketing", "UserRoleWarehouseManager", "UserRoleWarehouseOperator" ] }, "security.CustodyEvent": { "properties": { "action": { "description": "e.g. \"collected\", \"transferred\", \"reviewed\", \"sealed\"", "type": "string" }, "actor_id": { "type": "string" }, "occurred_at": { "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "security.EvidenceRecord": { "properties": { "chain_of_custody": { "items": { "$ref": "#/components/schemas/security.CustodyEvent" }, "type": "array", "uniqueItems": false }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "collected_at": { "type": "string" }, "collected_by": { "type": "string" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "data_owner_id": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "description": { "type": "string" }, "evidence_type": { "description": "e.g. \"log\", \"screenshot\", \"export\", \"provider_report\"", "type": "string" }, "hash_algorithm": { "type": "string" }, "hash_value": { "type": "string" }, "id": { "type": "string" }, "legal_hold": { "type": "boolean" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "source": { "type": "string" }, "storage_uri": { "type": "string" } }, "type": "object" }, "security.HistoryChange": { "properties": { "field": { "type": "string" }, "from_value": { "type": "string" }, "to_value": { "type": "string" } }, "type": "object" }, "security.HistoryEntry": { "properties": { "actor_domain": { "$ref": "#/components/schemas/security_enums.IdentityDomain" }, "actor_email": { "type": "string" }, "actor_id": { "type": "string" }, "actor_role": { "type": "string" }, "changes": { "items": { "$ref": "#/components/schemas/security.HistoryChange" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "note": { "type": "string" }, "occurred_at": { "type": "string" }, "reason_code": { "type": "string" }, "related_resource": { "type": "string" }, "related_resource_id": { "type": "string" }, "risk_flags": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "risk_level": { "$ref": "#/components/schemas/security_enums.SecurityRiskLevel" }, "sequence": { "type": "integer" }, "source": { "type": "string" }, "summary": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "security.ObjectMedia": { "description": "Avatar is the nested object projection (security.ObjectMedia), the exact\nshape Backend-Customers returns from POST /users/me/avatar/finalize so a\nclient can PATCH it straight back. Only Avatar.Code is honoured and saved;\ncustomer ownership is checked against the authoritative Customers media\nrecord. URLs are not proof of ownership. Omitting the field\nleaves the avatar untouched; sending it with a blank code clears it.", "properties": { "code": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "security.SecurityEvent": { "properties": { "actor_domain": { "$ref": "#/components/schemas/security_enums.IdentityDomain" }, "actor_email": { "type": "string" }, "actor_id": { "type": "string" }, "actor_role": { "type": "string" }, "assigned_to": { "type": "string" }, "auth_identity_id": { "type": "string" }, "category": { "description": "e.g. \"auth\", \"access\", \"data\", \"cloud\", \"payment\"", "type": "string" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "data_owner_id": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "description": { "type": "string" }, "detected_at": { "type": "string" }, "evidence_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "identity_domain": { "$ref": "#/components/schemas/security_enums.IdentityDomain" }, "legal_hold": { "type": "boolean" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "related_access_log_id": { "type": "string" }, "related_audit_log_id": { "type": "string" }, "reported_at": { "type": "string" }, "resolution": { "type": "string" }, "resolved_at": { "type": "string" }, "resource": { "type": "string" }, "resource_id": { "type": "string" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "risk_level": { "$ref": "#/components/schemas/security_enums.SecurityRiskLevel" }, "severity": { "$ref": "#/components/schemas/security_enums.SecurityEventSeverity" }, "source": { "type": "string" }, "status": { "$ref": "#/components/schemas/security_enums.SecurityEventStatus" }, "subject_account_id": { "type": "string" }, "subject_user_id": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "security.SecurityIncident": { "properties": { "affected_data": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "affected_systems": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "closed_at": { "type": "string" }, "commander_id": { "type": "string" }, "containment_summary": { "type": "string" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "customer_impact": { "type": "string" }, "data_owner_id": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "description": { "type": "string" }, "event_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "evidence_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "legal_hold": { "type": "boolean" }, "lessons_learned": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "notifiable_breach": { "type": "boolean" }, "notification_due_at": { "type": "string" }, "opened_at": { "type": "string" }, "owner_id": { "type": "string" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "recovery_summary": { "type": "string" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "root_cause": { "type": "string" }, "severity": { "$ref": "#/components/schemas/security_enums.SecurityEventSeverity" }, "status": { "$ref": "#/components/schemas/security_enums.SecurityEventStatus" }, "title": { "type": "string" } }, "type": "object" }, "security_enums.AuthAssuranceLevel": { "enum": [ "aal1", "aal2", "aal3" ], "type": "string", "x-enum-varnames": [ "AuthAssuranceLevel1", "AuthAssuranceLevel2", "AuthAssuranceLevel3" ] }, "security_enums.AuthMethod": { "enum": [ "password", "pin", "mfa", "passkey", "sso", "refresh_token", "api_key" ], "type": "string", "x-enum-varnames": [ "AuthMethodPassword", "AuthMethodPIN", "AuthMethodMFA", "AuthMethodPasskey", "AuthMethodSSO", "AuthMethodRefreshToken", "AuthMethodAPIKey" ] }, "security_enums.DataClassification": { "enum": [ "public", "internal", "confidential", "restricted" ], "type": "string", "x-enum-varnames": [ "DataClassificationPublic", "DataClassificationInternal", "DataClassificationConfidential", "DataClassificationRestricted" ] }, "security_enums.DataProtectionBasis": { "enum": [ "not_applicable", "consent", "contract", "legal_obligation", "legitimate_interest" ], "type": "string", "x-enum-varnames": [ "DataProtectionBasisNotApplicable", "DataProtectionBasisConsent", "DataProtectionBasisContract", "DataProtectionBasisLegalObligation", "DataProtectionBasisLegitimateInterest" ] }, "security_enums.IdentityDomain": { "enum": [ "customer", "workforce", "service" ], "type": "string", "x-enum-varnames": [ "IdentityDomainCustomer", "IdentityDomainWorkforce", "IdentityDomainService" ] }, "security_enums.SecurityEventSeverity": { "enum": [ "info", "low", "medium", "high", "critical" ], "type": "string", "x-enum-varnames": [ "SecurityEventSeverityInfo", "SecurityEventSeverityLow", "SecurityEventSeverityMedium", "SecurityEventSeverityHigh", "SecurityEventSeverityCritical" ] }, "security_enums.SecurityEventStatus": { "enum": [ "detected", "triaged", "investigating", "contained", "resolved", "false_positive" ], "type": "string", "x-enum-varnames": [ "SecurityEventStatusDetected", "SecurityEventStatusTriaged", "SecurityEventStatusInvestigating", "SecurityEventStatusContained", "SecurityEventStatusResolved", "SecurityEventStatusFalsePositive" ] }, "security_enums.SecurityRiskLevel": { "enum": [ "low", "medium", "high", "critical" ], "type": "string", "x-enum-varnames": [ "SecurityRiskLevelLow", "SecurityRiskLevelMedium", "SecurityRiskLevelHigh", "SecurityRiskLevelCritical" ] } }, "securitySchemes": { "BearerAuth": { "description": "User access JWT obtained through an Identity sign-in flow. Send as: `Bearer \u003ctoken\u003e`.", "in": "header", "name": "Authorization", "type": "apiKey" }, "ServiceBearerAuth": { "bearerFormat": "JWT", "description": "Service access token. Obtain one from POST /internal/token.", "scheme": "bearer", "type": "http" } } }, "externalDocs": { "description": "", "url": "" }, "info": { "contact": { "name": "Potato Mart Platform Team" }, "description": "Access JWTs optionally carry client_platform (web or mobile) attested by a verified registered federated-client flow. Password and legacy sessions omit this claim. Refresh preserves the stored attestation; device hints cannot set it.\nAccess JWTs always carry phone_verified next to email_verified. No sign-in waits on a phone; checkout reads the claim, and a refresh re-reads both after a verification.\nAccount-deletion restrictions return FORBIDDEN with details.reason=account_deletion_restricted and details.request_id on restricted authenticated routes. Active-request lookup and the narrow re-authentication/sign-out routes remain available.\nPotato Mart Backend-Identity service. Owns authentication\n(login, refresh, logout, email verification, password reset),\nstaff user accounts and RBAC roles, self-service devices,\naccount security, the service-to-service token issuer, and the\nread-only audit log. It also serves the internal identity\nprovisioning API consumed by Backend-Customers and the JWT-only\nPOS admission probe used by the same-origin gateway.\nJSON API responses generally use the shared envelope `{ \"success\": bool, \"data\": ..., \"error\": ... }`. Operations documented with HTTP 204 return no body; redirects and provider callbacks follow their documented response formats.", "license": { "name": "Proprietary" }, "title": "Backend-Identity API", "version": "47.3.0" }, "openapi": "3.1.0", "paths": { "/admin/account-deletion-requests": { "get": { "description": "Available only to Admin and SuperAdmin.", "parameters": [ { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Filter by state", "in": "query", "name": "state", "schema": { "type": "string" } }, { "description": "Comma-separated response fields", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_erasure.adminRequestListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List account-deletion requests for review", "tags": [ "erasure" ] } }, "/admin/account-deletion-requests/{requestId}/execute": { "post": { "description": "Available only to countryAdmin and superAdmin. Destructive execution and peer dispatch are separately feature-gated and disabled by default. Retention approval is also required before a lease or side effect; approval remains false, so execution cannot be activated by flags alone. No peer erasure endpoint is assumed by this API.", "parameters": [ { "description": "Account deletion request id", "in": "path", "name": "requestId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_erasure.adminRequestResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN when the last sign-in is older than five minutes or unknown, with details.reason=recent_authentication_required; disabled execution or unapproved retention also refuses. Retention refusal includes details.reason=retention_matrix_not_approved." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Execute or retry an approved account-deletion request", "tags": [ "erasure" ] } }, "/admin/account-deletion-requests/{requestId}/review": { "get": { "description": "Available only to Admin and SuperAdmin.", "parameters": [ { "description": "Account deletion request id", "in": "path", "name": "requestId", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated response fields", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_erasure.adminRequestResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get an account-deletion request for review", "tags": [ "erasure" ] }, "post": { "description": "Available only to Admin and SuperAdmin. An action-required decision preserves the restriction; approving does not erase data.", "parameters": [ { "description": "Account deletion request id", "in": "path", "name": "requestId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_erasure.reviewRequest", "description": "Review decision", "summary": "body" } ] } } }, "description": "Review decision", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_erasure.adminRequestResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Approve or require customer action for an account-deletion request", "tags": [ "erasure" ] } }, "/audit-logs": { "get": { "description": "Read-only, paginated, filterable view of the audit trail.", "parameters": [ { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Filter by actor id", "in": "query", "name": "actor_id", "schema": { "type": "string" } }, { "description": "Filter by action", "in": "query", "name": "action", "schema": { "type": "string" } }, { "description": "Filter by resource", "in": "query", "name": "resource", "schema": { "type": "string" } }, { "description": "Filter by outcome", "in": "query", "name": "outcome", "schema": { "type": "string" } }, { "description": "Start of range (RFC3339)", "in": "query", "name": "from", "schema": { "type": "string" } }, { "description": "End of range (RFC3339)", "in": "query", "name": "to", "schema": { "type": "string" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Query audit logs", "tags": [ "audit" ] } }, "/auth/federated/apple/events": { "post": { "description": "Answers 404 when no Apple client registration is configured.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_federatedauth.appleEventRequest", "description": "Apple-signed JWS payload", "summary": "body" } ] } } }, "description": "Apple-signed JWS payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Accepted: {\"success\":true}" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "summary": "Receive a signed Sign in with Apple lifecycle event", "tags": [ "auth" ] } }, "/auth/federated/email-captures/request": { "post": { "description": "A web LINE or Facebook sign-in or link whose provider shared no usable email redirects to the completion URI with email_capture_id and expires_at. The storefront server submits the shopper's address with that bearer and the device key from its HttpOnly device cookie. Identity sends a flow-bound code to the address and answers with email_verification_id, which completes at /auth/federated/email-verifications/{id}/complete. The bearer lives for FEDERATED_AUTH_CHALLENGE_TTL (ten minutes by default), is bound to the provider account and the device the flow started on, and is replaced by a newer sign-in with the same provider account. The same address again answers the code already sent; a new address sends a new code and retires the previous one. At most three codes are sent, counting failed deliveries. While another submission holds the 45-second lease, a valid capture on the same device returns 409 with details.reason=email_capture_in_progress and Retry-After; wait and retry the same bearer and address to reuse the code once the lease is released.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_federatedauth.EmailCaptureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_federatedauth.CompleteResponse" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR, including an address that is not a single plain mailbox; no code is spent" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "AUTH_REAUTH_REQUIRED for an unknown, expired, replaced or tampered bearer, another device, or an exhausted capture without a reusable result for this address, including while its lease is held. Start the provider sign-in again on this device. No busy state or Retry-After is disclosed for these captures." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT with details.reason=email_capture_in_progress and details.retry_after_seconds when another submission holds a valid capture's lease on this device. Retry the same bearer and address after the wait; after release the already-sent email_verification_id is reused without another email or attempt.", "headers": { "Retry-After": { "description": "Remaining lease seconds, rounded up to a positive integer", "schema": { "minimum": 1, "type": "integer" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "SERVICE_UNAVAILABLE when capture persistence is unavailable or the code could not be sent. A failed delivery counts as one of the three codes; retry with the same bearer." } }, "summary": "Submit the email for a web LINE or Facebook sign-in", "tags": [ "auth" ] } }, "/auth/federated/email-verifications/{id}/complete": { "post": { "description": " No sign-in waits on a phone. A web sign-in answers a grant, exchanged at /auth/federated/grants/exchange with the flow's device_key. A web link answers link_confirmation_id and expires_at, confirmed at /users/me/federated-identities/link-confirmations/complete.", "parameters": [ { "description": "Verification id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_federatedauth.emailVerificationRequest", "description": "One-time code", "summary": "body" } ] } } }, "description": "One-time code", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_federatedauth.CompleteResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_federatedauth.ProviderAccountLinkedElsewhereResponse" } } }, "description": "Verified explicit native link only. The provider subject is already linked to another account. No account, identity, email, issuer, or provider subject is disclosed. No login session is created. Other credential, device, or flow refusals remain neutral 401." } }, "summary": "Complete a flow-bound LINE or Facebook email verification", "tags": [ "auth" ] } }, "/auth/federated/facebook/data-deletion": { "post": { "description": "Answers 404 when no Facebook client registration is configured.", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "type": "string" }, { "title": "signed_request", "type": "string" } ] } } }, "description": "Facebook HMAC-signed request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_federatedauth.FacebookDeletionResult" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "summary": "Receive a signed Facebook data-deletion request", "tags": [ "auth" ] } }, "/auth/federated/facebook/data-deletion/status/{code}": { "get": { "description": "PII-free public status used by Facebook deletion confirmation URLs.", "parameters": [ { "description": "Opaque confirmation code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "summary": "Get an opaque provider erasure-review status", "tags": [ "auth" ] } }, "/auth/federated/grants/exchange": { "post": { "description": "Redeems a web login grant for its token pair, on the device the flow started with. The storefront server sends the device key from its HttpOnly device cookie. Any presentation spends the grant; one from another device also ends the session it carried. A web step-up re-authentication redeems its grant here too.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_federatedauth.grantExchangeRequest", "description": "One-time grant and the device the flow started with", "summary": "body" } ] } } }, "description": "One-time grant and the device the flow started with", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR, including a missing device_key; the grant is not spent" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "AUTH_INVALID_CREDENTIALS for an unknown, expired or used grant, or one presented from another device" } }, "summary": "Exchange a one-time web login grant", "tags": [ "auth" ] } }, "/auth/federated/{provider}/callback": { "get": { "parameters": [ { "description": "Federated provider", "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "google", "apple", "line", "facebook" ], "type": "string" } }, { "description": "One-time state", "in": "query", "name": "state", "required": true, "schema": { "type": "string" } }, { "description": "Authorization code; absent when the provider reports an error", "in": "query", "name": "code", "schema": { "type": "string" } }, { "description": "RFC 9207 authorization-response issuer (required for Google)", "in": "query", "name": "iss", "schema": { "type": "string" } }, { "description": "Provider authorization error, for example access_denied when the user cancels", "in": "query", "name": "error", "schema": { "type": "string" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "303": { "description": "See Other. Redirects to the web registration's completion_redirect_uri with exactly one outcome: grant; email_verification_id; email_capture_id and expires_at (LINE or Facebook shared no usable email; submit one to /auth/federated/email-captures/request); link_confirmation_id and expires_at (a web link, which commits only at /users/me/federated-identities/link-confirmations/complete); or error=cancelled (the user declined while the web flow was live) or error=failed (any other provider error, a missing code, a failed completion, or a known expired, consumed or deleted web flow). Inactive web flows return only error=failed, including cancellation and missing-code callbacks, until 24 hours after authentication-flow expiry. Minimal trusted routing and expiry metadata is retained separately; it cannot authenticate a callback. Retention expiry is enforced independently of asynchronous TTL deletion. Provider error text is never forwarded, and a provider error leaves a live flow live. The state identifies a live single-use flow, not the browser that started it, so nothing in the redirect is usable on its own: a grant is exchanged, and a link confirmed, only with the device key the flow started with." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Neutral AUTH_INVALID_CREDENTIALS for unknown states, native flows, wrong providers, unsafe redirects, lookup failures, or inactive web flows without retained routing metadata or outside retention." } }, "summary": "Complete web federated login callback", "tags": [ "auth" ] }, "post": { "parameters": [ { "description": "Federated provider", "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "apple" ], "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "type": "string" }, { "title": "state", "type": "string" }, { "title": "code", "type": "string" }, { "title": "error", "type": "string" }, { "title": "user", "type": "string" } ] } } }, "description": "One-time state | Authorization code | Provider error, for example user_cancelled_authorize | Apple's user JSON, sent on the first authorization; its name names only an account Identity creates", "required": true }, "responses": { "303": { "description": "See Other. Same completion outcomes as the GET callback, including error=cancelled for live cancellation and only error=failed for known inactive web flows retained until 24 hours after flow expiry." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Neutral AUTH_INVALID_CREDENTIALS for unknown states, native flows, wrong providers, unsafe redirects, lookup failures, or inactive web flows without retained routing metadata or outside retention." } }, "summary": "Complete Apple web federated login callback", "tags": [ "auth" ] } }, "/auth/federated/{provider}/complete": { "post": { "description": "Completes a started flow with exactly one provider credential: an authorization code, a native Facebook (Limited Login) or Apple-iOS signed assertion, or, for native Facebook only, a Graph user access token in access_token. A Graph access token carries no nonce; the single-use, device-bound state binds the completion, and the token must be fresh: Graph issued_at must be present and no earlier than the flow start minus 30 seconds, for sign-in, link and step-up alike, else the neutral 401. Sign in to Facebook after starting the flow. Facebook on the web completes at the callback with an authorization code. A new retail account signs in at once; no completion waits on a phone. A step-up re-authentication started at /users/me/reauthentications/{provider}/flows completes here too and answers a new session for the same customer, or the neutral 401. A verified explicit native link to another account returns 409 CONFLICT with details.reason provider_account_linked_elsewhere; ordinary sign-in never exposes this link-specific refusal.", "parameters": [ { "description": "Federated provider", "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "google", "apple", "line", "facebook" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_federatedauth.completeRequest", "description": "Authorization code, a native Facebook or Apple-iOS signed assertion, or a native Facebook access token", "summary": "body" } ] } } }, "description": "Authorization code, a native Facebook or Apple-iOS signed assertion, or a native Facebook access token", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_federatedauth.CompleteResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR. The body is malformed, has an unknown field, or does not carry exactly one of code, assertion, and access_token, or carries a credential this provider/platform does not complete with (access_token is accepted only for facebook on ios or android)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "AUTH_INVALID_CREDENTIALS. When a LINE or Facebook sign-in verified but neither the request nor the provider supplied an address for the Potato Mart email code, details.reason is federated_email_required, details.provider names the provider, and details.email_capture_id with details.expires_at is a capture bound to this device_key: send the address with a new complete, or submit it to /auth/federated/email-captures/request. Other credential, flow, device, and sign-in failures have no details. Verified explicit link ownership refusals use 409." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_federatedauth.ProviderAccountLinkedElsewhereResponse" } } }, "description": "Verified explicit native link only. The provider subject is already linked to another account. No account, identity, email, issuer, or provider subject is disclosed. No login session is created. Other credential, device, or flow refusals remain neutral 401." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "SERVICE_UNAVAILABLE. Facebook Graph failed or throttled while a native access_token was checked, or another dependency of the completion failed. The flow is spent; retry with a new flow." } }, "summary": "Complete native federated login", "tags": [ "auth" ] } }, "/auth/federated/{provider}/flows": { "post": { "description": "Creates one PKCE/state/nonce-bound Google, Apple, LINE, or Facebook login flow for an exact dev client registration.", "parameters": [ { "description": "Federated provider", "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "google", "apple", "line", "facebook" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_federatedauth.startRequest", "description": "Registered client and device", "summary": "body" } ] } } }, "description": "Registered client and device", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" } }, "summary": "Start federated login", "tags": [ "auth" ] } }, "/auth/forgot-password": { "post": { "description": "Requests a single-use password recovery link for an eligible retail customer. Public.\nExisting password accounts can reset their password. Social-only customers can set their first password when their current canonical email is verified and an active Google, Apple, LINE or Facebook binding is eligible.\nFirst-password setup requires unambiguous canonical customer ownership and no customer password credential, including inactive credentials. Provider email aliases cannot select an owner.\nControl, wholesale and Events requests are neutral no-ops with no challenge or email; administrator-issued links are outside this flow.\nUnknown, inactive, wrong-portal and handled delivery failures receive the same empty 204 response. Tokens expire after one hour.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_authn.forgotPasswordReq", "description": "Account email", "summary": "body" } ] } } }, "description": "Account email", "required": true }, "responses": { "204": { "description": "Neutral acknowledgement; does not confirm account existence or email delivery." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from the per-IP limiter on the public auth routes. The Retry-After header gives the wait; the envelope carries no details.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "summary": "Request a password reset", "tags": [ "auth" ] } }, "/auth/login": { "post": { "description": "Exchange email and password for an access + refresh token pair. Public. A stable client-generated device_key is required; display metadata is optional. A retail sign-in needs a verified email. After the password check, an unverified retail account answers 403 EMAIL_VERIFICATION_REQUIRED with no tokens and is emailed a fresh six-digit code (within the resend cooldown and hourly limit, silently). The app shows its code step, confirms with POST /auth/verify-email, and signs in again. A wrong password still answers 401 first, so the refusal reveals nothing about which accounts exist. Wholesale, staff, refresh and federated sign-in are not gated.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_authn.loginReq", "description": "Credentials", "summary": "body" } ] } } }, "description": "Credentials", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "data = { tokens, user }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "EMAIL_VERIFICATION_REQUIRED for a retail account whose email is not verified yet; a code has been emailed. AUTH_WRONG_PORTAL and AUTH_ACCOUNT_DISABLED are 401s." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from the per-IP limiter on the public auth routes. The Retry-After header gives the wait; the envelope carries no details.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "summary": "Log in", "tags": [ "auth" ] } }, "/auth/logout": { "post": { "description": "Revoke the supplied refresh token. Body is optional. Public.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_authn.logoutReq", "description": "Refresh token to revoke", "summary": "body" } ] } } }, "description": "Refresh token to revoke" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from the per-IP limiter on the public auth routes. The Retry-After header gives the wait; the envelope carries no details.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "summary": "Log out", "tags": [ "auth" ] } }, "/auth/logout-all": { "post": { "description": "Revoke every refresh token for the authenticated credential across its portal accounts.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" } }, "security": [ { "BearerAuth": [] } ], "summary": "Log out everywhere", "tags": [ "auth" ] } }, "/auth/pin-login": { "post": { "description": "Public sign-in for an active workforce password identity/account. Typed employee ID and employee-ID barcode input use this same route and both require the PIN. Employee IDs and PINs are exact ASCII-digit strings; no numeric conversion, partial matching, or other identifier lookup is performed. No terminal enrollment is required. Returns the usual token/profile envelope with the existing control audience and full current workforce permissions and geographic grants. The authoritative authentication method is pin, with no auth_time or MFA upgrade. Access, session, and refresh expiry are capped at the original sign-in plus 12 hours; refresh does not extend this absolute deadline. Inactivity is handled by the frontend. PIN sessions cannot manage PINs or satisfy recent-authentication checks. PIN login starts disabled. Disabled, unknown, unconfigured, locked, incorrect, or inactive credentials receive the same neutral 401 AUTH_INVALID_CREDENTIALS response without tokens. Six failed PIN attempts lock the credential until password-authorized replacement/removal. Durable device and IP budgets allow 33 validated requests per 15 minutes across replicas, including successful attempts. Cookie refresh transport uses the existing X-PM-Refresh-Transport and X-PM-CSRF protocol; body transport includes the refresh token. A requested device-salted offline verifier is issued only to a POS-authorized staff member, with a 12-hour absolute expiry. The response must not be cached.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.pinLoginReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.pinLoginResponse" } } }, "description": "data = {tokens, user, offline_credential?}; refresh_token omitted in cookie transport" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for malformed JSON, unknown fields, non-string or incorrectly formatted credentials, or an invalid device key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "AUTH_INVALID_CREDENTIALS for any unavailable or incorrect PIN credential, or disabled PIN login" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN when cookie refresh transport is requested without the required CSRF header" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from durable device/IP budgets or the existing public per-IP limiter", "headers": { "Retry-After": { "description": "Seconds until both exhausted durable windows can accept another request", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR when durable admission, grant resolution, or session issuance fails" } }, "security": [], "summary": "Sign in with employee ID and PIN", "tags": [ "auth" ] } }, "/auth/pin-login-policy": { "get": { "description": "Requires an active password-original control session and the current authoritative superAdmin role. No settings.read permission is required. PIN, SSO, customer, and other non-password sessions are refused. Returns only enabled; private admission generations are never exposed. A missing policy is disabled. This switch does not affect password login or portal PIN management.", "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.pinLoginPolicyResponse" } } }, "description": "Current PIN-login enablement" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Missing, mismatched, revoked, expired, or lifecycle-invalid session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN when the original method, persona, or live role is not an authorized superAdmin password session" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR when authoritative admission or policy persistence fails" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get the workforce PIN-login enablement policy", "tags": [ "auth" ] }, "put": { "description": "Requires an active password-original control session and the current authoritative superAdmin role, without settings.read or a separate current-password body field. Strictly accepts a required boolean enabled. The authenticated session, live identity/account/access/role, and policy mutation are fenced in one transaction. Every disable invalidates the generation held by existing PIN sessions and refresh credentials; re-enabling never revives them. Password login and portal PIN management remain available. Keep disabled until the separately delivered POS client passes compatibility and functional checks.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.setPINLoginPolicyReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.pinLoginPolicyResponse" } } }, "description": "Updated PIN-login enablement" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for malformed JSON, unknown fields, missing enabled, null, or a non-boolean value" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Missing, mismatched, revoked, expired, or lifecycle-invalid session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN when the original method, persona, or live role is not an authorized superAdmin password session" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR when transactional policy mutation fails" } }, "security": [ { "BearerAuth": [] } ], "summary": "Enable or disable workforce PIN login", "tags": [ "auth" ] } }, "/auth/pos-access": { "get": { "description": "Validates that the bearer token belongs to a current workforce role. Used by the POS gateway before proxying business API requests.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.posAccessResponse" } } }, "description": "{ success: true }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.posAccessErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.posAccessErrorResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Authorize POS portal access", "tags": [ "auth" ] } }, "/auth/pos-offline-revocations": { "post": { "description": "Requires an active workforce session with pos.access on this device. Reconcile each cached user and revision. Apply a returned decision only while the locally cached revision still matches that decision; an absent or erased credential is invalid. The response must not be cached.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "credentials": { "items": { "additionalProperties": false, "properties": { "revision": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "user_id": { "minLength": 1, "type": "string" } }, "required": [ "user_id", "revision" ], "type": "object" }, "maxItems": 10000, "type": "array" }, "device_key": { "maxLength": 128, "minLength": 16, "type": "string" } }, "required": [ "device_key", "credentials" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.OfflinePINRevocationsResponse" } } }, "description": "Live validity bound to each requested cached revision" }, "400": { "description": "Invalid device key" }, "401": { "description": "Missing or invalid session" }, "403": { "description": "Caller lacks POS permission or session belongs to another device" }, "500": { "description": "Authoritative credential status unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read device-bound offline credential revocations", "tags": [ "auth" ] } }, "/auth/referral-codes/check": { "post": { "description": "Public case-insensitive referral eligibility check. Returns only validity, never referrer identity or customer data. Uses the same per-IP rate-limit bucket as other public authentication routes. Malformed or unavailable provider checks fail closed with a sanitized 503.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.referralCheckReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.referralCheckResponse" } } }, "description": "Standard success envelope containing only data.valid" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for malformed JSON, extra fields or an empty/blank code" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS when the shared public auth IP bucket is exhausted", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "minimum": 1, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "SERVICE_UNAVAILABLE when authoritative referral validation cannot be established" } }, "security": [], "summary": "Check referral-code eligibility", "tags": [ "auth" ] } }, "/auth/refresh": { "post": { "description": "Exchange a valid refresh token for a new token pair. Public. JSON device_key is canonical for body transport; X-PM-Device-Key is used only by cookie transport. The stable key must match the credential binding.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_authn.refreshReq", "description": "Refresh token", "summary": "body" } ] } } }, "description": "Refresh token", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from the per-IP limiter on the public auth routes. The Retry-After header gives the wait; the envelope carries no details.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "summary": "Refresh tokens", "tags": [ "auth" ] } }, "/auth/register": { "post": { "description": "Creates or reuses a retail customer after credential proof and sends the email verification code (ten-minute expiry). Public registration accepts no phone field. Signed-in customers manage and verify their phone through POST /users/me/phone and POST /users/me/phone/verify. The verified email gates retail password sign-in (403 EMAIL_VERIFICATION_REQUIRED from /auth/login) and checkout, so the app goes straight to its code step. Nonblank referral codes are normalized and checked before account mutations; final Customers provisioning remains authoritative. Public. Fresh retail password signup always creates a private durable receipt and admission marker before Customers ensure. The exact eligible POS-profile conflict retains the new unverified account and sends its normal email code; it does not adopt a profile by email. Nonempty referral input is refused on this claim path. Ambiguous peer outcomes remain fenced and retry the same immutable input. No session is usable until exact Customers linkage is committed. The successful response remains HTTP 201 with the existing UserProfile shape; private receipt fields are never exposed.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.registerReq" } } }, "description": "New account", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.userProfileAPIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; authoritative referral refusals include details.referral_code=not_found, self_referral, or existing_profile for a POS profile claim. Unknown-code prevalidation creates no account." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "AUTH_INVALID_CREDENTIALS for an existing account without matching password proof." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from the per-IP limiter on the public auth routes. The Retry-After header gives the wait; the envelope carries no details.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "SERVICE_UNAVAILABLE when the referral precheck or Customers provisioning cannot be established; provider messages and details are sanitized." } }, "summary": "Register a customer account", "tags": [ "auth" ] } }, "/auth/resend-verification": { "post": { "description": "Rotates and emails a six-digit verification code for an unverified account in the selected portal. The response is neutral for unknown, ineligible, throttled, or delivery-failed accounts. It backs the resend action of the code step after registration, a sign-in refused with EMAIL_VERIFICATION_REQUIRED, or an email change. Public.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_authn.resendVerificationReq", "description": "Account email", "summary": "body" } ] } } }, "description": "Account email", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from the per-IP limiter on the public auth routes. The Retry-After header gives the wait; the envelope carries no details.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "summary": "Resend a verification email", "tags": [ "auth" ] } }, "/auth/reset-password": { "post": { "description": "Consumes an operation-bound retail recovery token and sets a password atomically. Existing-password resets revoke that password credential's sessions and refresh records. First-password setup inserts a password credential for the existing customer while preserving social bindings, sessions, refresh records and customer linkage. Current canonical email, ownership, credential state and active account/admission are rechecked. First setup rechecks verified canonical email, password absence and the exact social binding that issued the link. Legacy links without operation metadata, changed-email links, links invalidated by another password change and setup links invalidated by unlink/revocation/reactivation fail closed. Completion verifies the unchanged mailbox. Public. Distinct rr1-prefixed POS enrollment invitations have a one-hour expiry and require portal retail. Their claim rechecks the exact active POS Customers profile, identity tuple and unchanged canonical email, then atomically installs the first password, verifies the mailbox, clears the pending enrollment marker and consumes the invitation. Used, expired, replaced or changed-linkage invitations fail closed. This does not relax ordinary reset or social-first setup guards.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_authn.resetPasswordReq", "description": "Reset token and new password", "summary": "body" } ] } } }, "description": "Reset token and new password", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from the per-IP limiter on the public auth routes. The Retry-After header gives the wait; the envelope carries no details.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "summary": "Complete a password reset", "tags": [ "auth" ] } }, "/auth/sessions": { "get": { "description": "Returns up to 200 active sessions, newest first, including the verified caller's session even when it would fall outside the list limit. The default response contains exactly one current=true row; all other rows explicitly carry current=false. A caller session that is no longer eligible returns 401. Explicit fields projection can omit current; use fields=id,current to request only the session IDs and marker.", "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.loginSessionListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List the caller's login sessions", "tags": [ "auth-sessions" ] } }, "/auth/sessions/{id}": { "delete": { "parameters": [ { "description": "Session id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Revoke one of the caller's sessions", "tags": [ "auth-sessions" ] } }, "/auth/verify-email": { "post": { "description": "Consumes a single-use six-digit code for the supplied retail or wholesale account and marks the email verified. It issues no tokens, so an email code is never a sign-in credential. After a sign-in refused with EMAIL_VERIFICATION_REQUIRED, sign in again with the password. Public. For a pending POS profile claim, consuming the code atomically verifies the mailbox and records durable claim readiness. The claim then checks the exact active POS profile through authenticated Customers mutation; a peer failure leaves the account fenced for password-proven sign-in or bounded recovery retries. A valid consumed code still returns the established HTTP 200 success envelope even when linkage is pending; the code cannot be replayed to sign in.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_authn.verifyEmailReq", "description": "Email verification code", "summary": "body" } ] } } }, "description": "Email verification code", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from the per-IP limiter on the public auth routes. The Retry-After header gives the wait; the envelope carries no details.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "summary": "Verify a customer email", "tags": [ "auth" ] } }, "/auth/verify-password": { "post": { "description": "Re-verifies the exact active password credential bound to the current JWT session. Wrong or unusable passwords return AUTH_PASSWORD_VERIFICATION_FAILED without invalidating or refreshing the session.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.verifyPasswordReq" } } }, "description": "Password verification request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.verifyPasswordResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.verifyPasswordFailureResponse" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Seconds until both user and IP windows can accept another attempt", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Verify the authenticated user's password", "tags": [ "auth" ] } }, "/devices": { "get": { "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_devices.userDeviceListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List the caller's devices", "tags": [ "devices" ] }, "post": { "description": "Binds the authenticated session and its rotating refresh credential to this explicit installation key. A different existing explicit binding is rejected.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_devices.RegisterInput", "description": "Device to register", "summary": "body" } ] } } }, "description": "Device to register", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_devices.userDeviceResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Register or refresh the caller's device", "tags": [ "devices" ] } }, "/devices/seen": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_devices.SeenInput", "description": "Device-seen event", "summary": "body" } ] } } }, "description": "Device-seen event", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_devices.userDeviceSeenResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Record a device-seen event for the caller", "tags": [ "devices" ] } }, "/devices/stats": { "get": { "description": "Admin analytics aggregate over non-revoked retail and/or wholesale devices, scoped to the caller's matching read permissions. Control-portal registrations are never returned.", "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_devices.deviceStatsResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Device registration counts by portal and type", "tags": [ "devices" ] } }, "/devices/{deviceKey}": { "delete": { "parameters": [ { "description": "Device key", "in": "path", "name": "deviceKey", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "{ success: true }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Revoke one of the caller's devices", "tags": [ "devices" ] }, "get": { "parameters": [ { "description": "Device key", "in": "path", "name": "deviceKey", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_devices.userDeviceResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get one of the caller's devices", "tags": [ "devices" ] } }, "/devices/{deviceKey}/push-destination": { "delete": { "parameters": [ { "description": "Current device key", "in": "path", "name": "deviceKey", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_pushdestinations.RevocationAPIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" } }, "security": [ { "BearerAuth": [] } ], "summary": "Revoke every push destination bound to the current device", "tags": [ "devices" ] }, "put": { "parameters": [ { "description": "Current device key", "in": "path", "name": "deviceKey", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_pushdestinations.RegisterInput", "description": "FCM destination binding", "summary": "body" } ] } } }, "description": "FCM destination binding", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_pushdestinations.RegistrationAPIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Register the current device's protected push destination", "tags": [ "devices" ] } }, "/devices/{deviceKey}/trust": { "patch": { "parameters": [ { "description": "Device key", "in": "path", "name": "deviceKey", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_devices.TrustInput", "description": "Trust flag", "summary": "body" } ] } } }, "description": "Trust flag", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_devices.userDeviceResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Set the trusted flag on one of the caller's devices", "tags": [ "devices" ] } }, "/me/account-deletion-requests": { "get": { "description": "Reads the authenticated retail account's active request, including while account-deletion restrictions apply. No request ID, idempotency key or recent-authentication challenge is required. This read has no creation side effect and returns 404 when no active request exists. The customer projection excludes private review and peer receipts.", "parameters": [ { "description": "Comma-separated response fields", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_erasure.customerRequestResponse" } } }, "description": "Active request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Only authenticated retail customer accounts may use this route" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "No active request" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Account restriction status is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Discover your active account-deletion request", "tags": [ "erasure" ] }, "post": { "description": "Creates or returns one active, durable deletion-review request for the authenticated retail account. The account remains restricting until every service returns its durable restriction receipt; a partial receipt set returns 503 with the durable request ID and Retry-After. Recording is feature-gated; destructive execution remains separately disabled by default.", "parameters": [ { "description": "Client-generated idempotency key (16-512 characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_erasure.customerRequestResponse" } } }, "description": "Existing active request (idempotent replay)" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_erasure.customerRequestResponse" } } }, "description": "Created" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN when the last sign-in is older than five minutes or unknown, with details.reason=recent_authentication_required, or when this account may not use the route" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Waiting for all peer receipts; details include request_id, retry_after_seconds and action. Retry-After is the earliest pending deadline rounded up to at least one second.", "headers": { "Retry-After": { "description": "Seconds until the next pending peer retry", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Request deletion of your retail account", "tags": [ "erasure" ] } }, "/me/account-deletion-requests/{requestId}": { "delete": { "description": "Cancellation is accepted until the request has atomically entered execution. Access remains restricted while every service records its idempotent unrestriction receipt; a partial receipt set returns 503 with Retry-After.", "parameters": [ { "description": "Account deletion request id", "in": "path", "name": "requestId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_erasure.customerRequestResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Waiting for all peer receipts; details include request_id, retry_after_seconds and action. Retry-After is the earliest pending deadline rounded up to at least one second.", "headers": { "Retry-After": { "description": "Seconds until the next pending peer retry", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Cancel your pending account-deletion request", "tags": [ "erasure" ] }, "get": { "parameters": [ { "description": "Account deletion request id", "in": "path", "name": "requestId", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated response fields", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_erasure.customerRequestResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get your active account-deletion request", "tags": [ "erasure" ] } }, "/me/account-deletion-requests/{requestId}/acknowledgements": { "post": { "description": "The route is reserved for the versioned stored-value and action-required acknowledgement flow. It is intentionally feature-gated until the Pricing recovery-claim integration can validate the submitted snapshot and recovery code without retaining plaintext value data.", "parameters": [ { "description": "Account deletion request id", "in": "path", "name": "requestId", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN when the last sign-in is older than five minutes or unknown, with details.reason=recent_authentication_required, or when this account may not use the route" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Acknowledge an account-deletion action requirement", "tags": [ "erasure" ] } }, "/permissions": { "get": { "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List all assignable permissions", "tags": [ "roles" ] } }, "/roles": { "get": { "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List roles", "tags": [ "roles" ] } }, "/roles/{key}": { "get": { "parameters": [ { "description": "Role key", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a role and its permissions", "tags": [ "roles" ] } }, "/roles/{key}/permissions": { "put": { "parameters": [ { "description": "Role key", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_roles.setPermissionsReq", "description": "Permission keys", "summary": "body" } ] } } }, "description": "Permission keys", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Replace a role's permissions", "tags": [ "roles" ] } }, "/security/access-logs": { "get": { "parameters": [ { "description": "Filter by actor id", "in": "query", "name": "actor_id", "schema": { "type": "string" } }, { "description": "Filter by action", "in": "query", "name": "action", "schema": { "type": "string" } }, { "description": "Filter on/after (RFC3339 or YYYY-MM-DD)", "in": "query", "name": "from", "schema": { "type": "string" } }, { "description": "Filter on/before (RFC3339 or YYYY-MM-DD)", "in": "query", "name": "to", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List access-log entries", "tags": [ "security" ] } }, "/security/cloud-profiles": { "get": { "parameters": [ { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List cloud-service security profiles", "tags": [ "security" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_security.CloudServiceSecurityProfile", "description": "Cloud profile to create", "summary": "body" } ] } } }, "description": "Cloud profile to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a cloud-service security profile", "tags": [ "security" ] } }, "/security/cloud-profiles/{id}": { "delete": { "parameters": [ { "description": "Cloud profile id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete a cloud-service security profile", "tags": [ "security" ] }, "get": { "parameters": [ { "description": "Cloud profile id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a cloud-service security profile by id", "tags": [ "security" ] }, "put": { "parameters": [ { "description": "Cloud profile id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_security.CloudServiceSecurityProfile", "description": "Fields to update", "summary": "body" } ] } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a cloud-service security profile", "tags": [ "security" ] } }, "/security/events": { "get": { "parameters": [ { "description": "Filter by severity", "in": "query", "name": "severity", "schema": { "type": "string" } }, { "description": "Filter by status", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Filter by category", "in": "query", "name": "category", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List security events", "tags": [ "security" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/security.SecurityEvent", "description": "Security event to record", "summary": "body" } ] } } }, "description": "Security event to record", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Record a security event", "tags": [ "security" ] } }, "/security/events/{id}/status": { "patch": { "parameters": [ { "description": "Security event id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_security.UpdateEventStatusInput", "description": "Status transition", "summary": "body" } ] } } }, "description": "Status transition", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a security event's status", "tags": [ "security" ] } }, "/security/evidence": { "get": { "parameters": [ { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List evidence records", "tags": [ "security" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/security.EvidenceRecord", "description": "Evidence record to create", "summary": "body" } ] } } }, "description": "Evidence record to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create an evidence record", "tags": [ "security" ] } }, "/security/evidence/{id}": { "get": { "parameters": [ { "description": "Evidence record id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get an evidence record by id", "tags": [ "security" ] } }, "/security/evidence/{id}/custody": { "post": { "parameters": [ { "description": "Evidence record id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_security.CustodyInput", "description": "Custody event to append", "summary": "body" } ] } } }, "description": "Custody event to append", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Append a chain-of-custody event to an evidence record", "tags": [ "security" ] } }, "/security/incidents": { "get": { "parameters": [ { "description": "Filter by status", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List security incidents", "tags": [ "security" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/security.SecurityIncident", "description": "Incident to create", "summary": "body" } ] } } }, "description": "Incident to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a security incident", "tags": [ "security" ] } }, "/security/incidents/{id}": { "get": { "parameters": [ { "description": "Incident id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a security incident by id", "tags": [ "security" ] }, "put": { "parameters": [ { "description": "Incident id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/security.SecurityIncident", "description": "Fields to update", "summary": "body" } ] } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a security incident", "tags": [ "security" ] } }, "/security/incidents/{id}/events": { "post": { "parameters": [ { "description": "Incident id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_security.linkEventsReq", "description": "Event ids to link", "summary": "body" } ] } } }, "description": "Event ids to link", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Link security events to an incident", "tags": [ "security" ] } }, "/security/policy": { "get": { "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get the security policy settings", "tags": [ "security" ] }, "put": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_security.SecurityPolicySettings", "description": "Policy settings", "summary": "body" } ] } } }, "description": "Policy settings", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Replace the security policy settings", "tags": [ "security" ] } }, "/users": { "get": { "description": "Paginated, filterable list of staff user accounts.", "parameters": [ { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Field to sort by", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "Sort direction", "in": "query", "name": "order", "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Filter by role key", "in": "query", "name": "role", "schema": { "type": "string" } }, { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Filter by active state", "in": "query", "name": "active", "schema": { "type": "boolean" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List staff users", "tags": [ "users" ] }, "post": { "description": "Creates a staff user within the caller's own geographic scope. The submitted geo_scope must satisfy the target role's required level AND sit inside the caller's own scope: a countryAdmin for AU may staff AU only. A geo_scope outside the caller's own is refused with 403; creating staff in another country, or another global principal, requires superAdmin.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_users.CreateInput", "description": "New user", "summary": "body" } ] } } }, "description": "New user", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "geo_scope outside the caller's own scope, or no resolvable caller scope" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a staff user", "tags": [ "users" ] } }, "/users/bulk": { "patch": { "description": "Requires user.write and the same geographic scope as individual staff updates.\nAccepts 1-100 unique explicit user IDs and only patch.active. IDs are trimmed;\nObjectID hex IDs are lowercased. Each ID is at most 128 UTF-8 bytes without control characters.\nThe body limit is 128 KiB, including unknown-length bodies. Roles and grants cannot be changed.\nAll reads, validation and writes occur in one mandatory Mongo transaction.\nMissing and out-of-scope IDs both return 404 with details.missing_ids in request order.\nSuccess echoes normalized IDs and counts selected records, including already-matching records.\nRefetch the affected list after success; refetch before retrying an uncertain 500 outcome.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_users.BulkUpdateInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_users.BulkUpdateResponse" } } }, "description": "Entire batch committed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Invalid selection or activation flag" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Missing user.write or usable geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "One or more users missing or outside scope; nothing changed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Concurrent transaction conflict; refetch and retry" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Body exceeds 128 KiB" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Batch could not be confirmed; refetch before retrying" } }, "security": [ { "BearerAuth": [] } ], "summary": "Atomically activate or deactivate selected staff users", "tags": [ "users" ] } }, "/users/me": { "get": { "description": "Returns the profile of the authenticated caller. No special permission required.", "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get the current user", "tags": [ "users" ] }, "patch": { "description": "Updates the authenticated caller's own account. Only display name, customer email, MFA toggle, preferred language, and avatar may be changed here; role and active status are admin-only. avatar is the object projection {code, url} returned by the Customers avatar finalize call; only avatar.code is honoured and saved, so a caller-supplied url is never trusted. Fetch the signed avatar URL from Customers' owner-authorized download-url endpoint when displaying it. Sending avatar with a blank code clears the avatar; omitting avatar leaves it untouched. Avatar updates must reference finalized ACTIVE customer-avatar media owned by the caller where media metadata allows it. The target is always the caller (derived from the token), never an id in the body. Changing email to a new address (not only its letter case) clears email_verified, and a customer with retail password access is emailed a six-digit code at the new address, to confirm with POST /auth/verify-email (portal retail) or resend with POST /auth/resend-verification. Until then a retail password sign-in answers 403 EMAIL_VERIFICATION_REQUIRED; current sessions keep working. Workforce email replacement returns 400 VALIDATION_ERROR; employee IDs cannot be updated.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_users.SelfUpdateInput", "description": "Fields to update", "summary": "body" } ] } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update your own profile", "tags": [ "users" ] } }, "/users/me/federated-identities": { "get": { "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" } }, "security": [ { "BearerAuth": [] } ], "summary": "List the caller's connected login credentials", "tags": [ "users" ] } }, "/users/me/federated-identities/link-confirmations/complete": { "post": { "description": "A web link does not commit where the provider returns, because the provider's redirect comes from whichever browser holds the authorization URL. The completion redirect (or an email verification's result) carries link_confirmation_id and expires_at instead. The storefront server confirms it as the user who started the link, with the device key from its HttpOnly device cookie. The confirmation lives as long as a login grant (two minutes by default), and any presentation spends it. Starting the link required a recent sign-in; confirming it does not.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_federatedauth.LinkConfirmationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_federatedauth.CompleteResponse" } } }, "description": "Linked; data carries linked_identity_id" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; the confirmation is not spent" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "The access token is missing or invalid" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND for an unknown, expired or used confirmation, or one presented by another user or from another device, which spends it. Start the link again." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT when the provider account could not be linked. A proven binding to another account includes only details.reason provider_account_linked_elsewhere with message the provider account is linked to another account. Other link refusals retain the generic CONFLICT with no details. The confirmation is spent." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "SERVICE_UNAVAILABLE when the confirmation could not be read" } }, "security": [ { "BearerAuth": [] } ], "summary": "Confirm a web federated link", "tags": [ "users" ] } }, "/users/me/federated-identities/{id}": { "delete": { "description": "Requires a credential sign-in within the last five minutes. Refuses to unlink the credential used by the calling session with CONFLICT and details.reason=current_session_credential; first step up with a different linked provider or the password endpoint and use that new session. On success, revokes the binding, ends that binding's sessions and removes its stored provider credential while preserving the calling session. The same customer can link the provider account again after their own unlink, or after Apple revoked it on a consent they give again. A LINE unlink goes ahead even when LINE's deauthorization cannot be done; the skipped deauthorization is logged.", "parameters": [ { "description": "Authentication identity id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unlinked: {\"success\":true}" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "The access token is missing or invalid" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN when the last sign-in is older than five minutes or unknown, with details.reason=recent_authentication_required; start a re-authentication at /users/me/reauthentications/{provider}/flows and retry. Also FORBIDDEN for an account restricted for deletion." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when the binding is not one of this customer's" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT with details.reason=last_usable_credential for the final usable sign-in method, primary_credential for the customer's primary retail credential, or current_session_credential for the credential used by the calling session. The current-session check runs before provider revocation." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "SERVICE_UNAVAILABLE when Google, Apple or Facebook could not revoke the stored credential; never for LINE" } }, "security": [ { "BearerAuth": [] } ], "summary": "Unlink a federated login credential", "tags": [ "users" ] } }, "/users/me/federated-identities/{provider}/flows": { "post": { "description": "Requires a credential sign-in within the last five minutes. A native link completes at /auth/federated/{provider}/complete from the device that started it and links at once. A web link returns through the callback with link_confirmation_id and commits only at /users/me/federated-identities/link-confirmations/complete. A customer who signed in more than five minutes ago re-authenticates first at /users/me/reauthentications/{provider}/flows.", "parameters": [ { "description": "Federated provider", "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "google", "apple", "line", "facebook" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_federatedauth.startRequest", "description": "Registered client and device", "summary": "body" } ] } } }, "description": "Registered client and device", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for an unknown provider, a body that is not strict JSON, or an application_id that does not match the provider and platform (details.application_id)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "The access token is missing or invalid, or AUTH_INVALID_CREDENTIALS when the provider is not enabled for this platform" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN when the last sign-in is older than five minutes or unknown, with details.reason=recent_authentication_required; start a re-authentication at /users/me/reauthentications/{provider}/flows and retry. Also FORBIDDEN for an account restricted for deletion." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when federated sign-in is off" } }, "security": [ { "BearerAuth": [] } ], "summary": "Start linking a federated login credential", "tags": [ "users" ] } }, "/users/me/password": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_users.changePasswordReq", "description": "Current and new password", "summary": "body" } ] } } }, "description": "Current and new password", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" } }, "security": [ { "BearerAuth": [] } ], "summary": "Change your own password", "tags": [ "users" ] } }, "/users/me/phone": { "post": { "description": "Texts a six-digit code (ten-minute expiry) to the number a retail customer is adding or changing, for account completion and checkout; no sign-in waits on a phone. With no verified phone on record the number is stored at once, unverified. A verified phone stays in place while a new number is proven; it is replaced only when /users/me/phone/verify succeeds, so an abandoned change keeps it. Posting the same unverified number again resends the code; posting the verified phone answers phone_verified=true and sends nothing. No recent sign-in is required. A phone becomes exclusive to one account after successful SMS verification, including disabled accounts. Unverified numbers may be shared. An already-owned verified number is rejected before sending a code. Retail customer sessions only.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.PhoneRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.PhoneChallengeResponse" } } }, "description": "Code sent, or the number is already the verified phone" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR, including a number that is not canonical E.164" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "The access token is missing or invalid" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN for a session that is not a retail customer's, or an inactive account" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when the account no longer exists" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT when another account owns the verified phone (details.reason phone_already_verified), or the phone changed during the request; request the code again" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS inside the 60-second resend cooldown or after five codes in an hour, where the Retry-After header and details.retry_after_seconds give the wait. The per-IP limiter answers the same code with only the Retry-After header. Nothing is stored.", "headers": { "Retry-After": { "description": "Seconds to wait before requesting another code", "schema": { "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "SERVICE_UNAVAILABLE when the code could not be sent; the cooldown is released for an immediate retry" } }, "security": [ { "BearerAuth": [] } ], "summary": "Add or change the account phone", "tags": [ "users" ] } }, "/users/me/phone/verify": { "post": { "description": "Checks the code for the number being verified and makes it the account's verified phone. A wrong code spends one of five attempts. The access token carries phone_verified from the next refresh. Retail customer sessions only.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.PhoneConfirmRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Verified; data is the updated UserProfile" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR. A rejected code carries details.reason code_invalid (wrong or used code), code_expired, code_attempts_exceeded (request a new code) or no_pending_phone. Never a 401." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "The access token is missing or invalid" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN for a session that is not a retail customer's, or an inactive account" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when the account no longer exists" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT when another account owns the verified phone (details.reason phone_already_verified), with the pending code, attempt count and previous phone unchanged; or when the stored phone changed while the code was pending" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from the per-IP limiter" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "SERVICE_UNAVAILABLE when the code cannot be checked right now; ask again" } }, "security": [ { "BearerAuth": [] } ], "summary": "Verify the account phone", "tags": [ "users" ] } }, "/users/me/pin": { "get": { "description": "Returns safe PIN status for the caller's active workforce password identity and account. Requires an active password-original control session; refreshed password sessions retain that original method. Customer, PIN, SSO, non-control, and inactive sessions are refused. No settings.read or other broad settings permission is required. The PIN value and private credential state are never returned. This management endpoint is independent of PIN-login enablement.", "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.pinStatusResponse" } } }, "description": "Safe PIN status" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for an invalid response field projection" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Missing or invalid access token, or an inactive session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN for a caller without an active workforce password identity/account and a password-original control session" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR when credential or session verification fails" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get your workforce PIN status", "tags": [ "users" ] }, "post": { "description": "Verifies the current password and sets a six-digit PIN for the caller's active workforce password identity/account. Requires an active password-original control session, with no settings.read requirement. Refuses PIN and other non-password sessions even when a correct password is supplied. Supports repeated successful changes and forgotten or locked PIN replacement without the old PIN or a cooldown. The password proof is checked against the current credential at commit. Advances the private PIN revision, clears PIN attempt/lock state, and revokes affected PIN sessions and refresh records atomically. Existing password sessions remain usable. Returns only safe status; never the PIN value.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.setPINRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.pinStatusResponse" } } }, "description": "Updated safe PIN status" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for malformed JSON, unknown fields, missing password, or a PIN that is not exactly six ASCII digits as a string" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Missing or invalid access token, or an inactive session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN for a caller without an active workforce password identity/account and a password-original control session" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.verifyPasswordFailureResponse" } } }, "description": "AUTH_PASSWORD_VERIFICATION_FAILED for an incorrect, unusable, or stale current-password proof" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from durable authenticated password-verification user or IP budgets", "headers": { "Retry-After": { "description": "Seconds until both windows can accept another attempt", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR when password verification or atomic credential mutation fails" } }, "security": [ { "BearerAuth": [] } ], "summary": "Set or replace your workforce PIN", "tags": [ "users" ] } }, "/users/me/pin/remove": { "post": { "description": "Verifies the current password and removes the caller's PIN, advancing its private revision, clearing PIN attempt/lock state, and revoking affected PIN sessions and refresh records atomically. Requires an active workforce password identity/account and password-original control session, with no settings.read requirement. Refuses PIN and other non-password sessions even with the correct password. The old PIN is not required, including when locked. Existing password sessions remain usable. Returns safe PIN status, and never credential values or private state.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.removePINRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.pinStatusResponse" } } }, "description": "Updated safe PIN status" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for malformed JSON, unknown fields, or a missing current password" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Missing or invalid access token, or an inactive session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN for a caller without an active workforce password identity/account and a password-original control session" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.verifyPasswordFailureResponse" } } }, "description": "AUTH_PASSWORD_VERIFICATION_FAILED for an incorrect, unusable, or stale current-password proof" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from durable authenticated password-verification user or IP budgets", "headers": { "Retry-After": { "description": "Seconds until both windows can accept another attempt", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR when password verification or atomic credential mutation fails" } }, "security": [ { "BearerAuth": [] } ], "summary": "Remove your workforce PIN", "tags": [ "users" ] } }, "/users/me/pin/reveal": { "get": { "description": "Returns the caller's own six-digit PIN on explicit request. Requires an active password-original workforce control session and active password identity/account, with no settings.read requirement. PIN, SSO, customer, revoked, expired, and inactive sessions are refused. The response is never cached. Audit metadata contains only a redacted outcome. This read does not change the PIN, lock state, or PIN-login policy. General status and profile reads never return the PIN.", "parameters": [ { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.pinRevealResponse" } } }, "description": "Own six-digit PIN", "headers": { "Cache-Control": { "schema": { "const": "no-store", "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for an invalid response field projection" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Missing or invalid access token, or an inactive session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN without an active password-original workforce control session" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when no PIN is configured" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR when credential or session verification fails" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reveal your own workforce PIN", "tags": [ "users" ] } }, "/users/me/reauthentications/password": { "post": { "description": "Verifies the calling customer's active password credential, including when the current session used a provider. Requires an active retail session but no recent-sign-in check. Returns a new session for the same customer and account with fresh auth_time and the stored device binding; the old session remains active and may be logged out separately. Does not rerun public login, provision an account or send email verification. Uses the authenticated password verification user/IP attempt limits. No user, account, portal or device overrides are accepted. Password authentication does not establish a trusted client platform. X-PM-Refresh-Transport=cookie uses the existing HttpOnly refresh cookie and requires X-PM-CSRF=1; otherwise refresh_token is in the response body.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "password": { "format": "password", "minLength": 1, "type": "string", "writeOnly": true } }, "required": [ "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_authn.passwordReauthenticationResponse" } } }, "description": "New session for the calling customer only" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for a malformed, missing or unknown field" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Missing or invalid access token, or neutral AUTH_INVALID_CREDENTIALS (federated authentication failed) for a refused session or password proof, as with provider step-up" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN for missing cookie-mode CSRF proof or account deletion restrictions" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS from the authenticated password verification user or IP window", "headers": { "Retry-After": { "description": "Seconds until both windows can accept another attempt", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR when credential/session verification or atomic session persistence fails" } }, "security": [ { "BearerAuth": [] } ], "summary": "Step up the current retail customer session with its password", "tags": [ "auth" ] } }, "/users/me/reauthentications/{provider}/flows": { "post": { "description": "Starts a step-up re-authentication for a signed-in retail customer, with a provider account already linked to them. The body and result are the sign-in start's. Complete it like a sign-in, natively at /auth/federated/{provider}/complete or on the web through the callback and /auth/federated/grants/exchange. The result is a new session for the same customer whose sign-in time passes the five-minute check on linking, unlinking and account deletion. Google shows its account chooser (it cannot be made to ask for a password), LINE its login screen, Facebook on the web a password prompt; Apple is interactive anyway. LINE and Apple must report a sign-in at or after the flow started; Google and Facebook count the completion. Any refusal at completion is the neutral 401. Check that the new session's profile is the same customer, switch to it and log the old refresh token out. Needs no recent sign-in itself, and stays open to an account restricted for deletion.", "parameters": [ { "description": "Federated provider", "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "google", "apple", "line", "facebook" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_federatedauth.startRequest" } } }, "description": "Registered client and device, exactly as for a sign-in start", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK; data is the sign-in start result (flow_id, authorization_url, and state and nonce for an app)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for an unknown provider, a body that is not strict JSON, or an application_id that does not match the provider and platform" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "The access token is missing or invalid, or AUTH_INVALID_CREDENTIALS when the provider is not enabled for this platform" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN for a session that is not a retail customer's" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when federated sign-in is off" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT with details.reason=provider_not_linked when the customer has no active binding for this provider" } }, "security": [ { "BearerAuth": [] } ], "summary": "Start a step-up re-authentication", "tags": [ "users" ] } }, "/users/{id}": { "delete": { "description": "SuperAdmin-only workforce break-glass deletion. Retail customer accounts are rejected and must use the durable account-deletion request workflow.", "parameters": [ { "description": "User id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete a staff user", "tags": [ "users" ] }, "get": { "description": "Reads one staff user within the caller's geographic scope. A user outside that scope is reported as 404, identically to an id that does not exist, so the endpoint cannot be used to probe for staff in other countries.", "parameters": [ { "description": "User id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated JSON fields or approved dotted JSON paths to project from the response", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a staff user by id", "tags": [ "users" ] }, "patch": { "description": "Patches a staff user within the caller's geographic scope. A user outside that scope is reported as 404, identically to an id that does not exist. The submitted geo_scope is validated twice: against the target role's required level, and against the caller's own scope. Moving a staff member outside the caller's geography — an AU countryAdmin sending country_code NZ, say — is refused with 403, not 404, because the target is one the caller can already see and the rejected value came from their own request body.", "parameters": [ { "description": "User id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_users.UpdateInput", "description": "Fields to update", "summary": "body" } ] } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a staff user", "tags": [ "users" ] } }, "/users/{id}/password": { "post": { "description": "Force-sets the target staff user's password without knowing the current one, within the caller's geographic scope. A user outside that scope is reported as 404, identically to an id that does not exist. Every refresh token and login session for the target's credential is revoked, so the new password is the only way back in. The password itself is never audited.", "parameters": [ { "description": "User id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_users.setPasswordReq", "description": "New password", "summary": "body" } ] } } }, "description": "New password", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Set a staff user's password", "tags": [ "users" ] } }, "/users/{id}/verify-email": { "post": { "description": "Idempotently marks the located user's email as verified, within the caller's geographic scope. A user outside that scope is reported as 404, identically to an id that does not exist, and nothing is written. A reason is required; actor identity and timestamp are server-derived and an immutable audit record is returned.", "parameters": [ { "description": "User id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_users.ManualEmailVerificationInput", "description": "Manual verification reason", "summary": "body" } } }, "description": "Manual verification reason", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_users.verifyEmailResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Identity_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Verify a user's email", "tags": [ "users" ] } } }, "servers": [ { "url": "/v1" } ] }