> ## Documentation Index > Fetch the complete documentation index at: https://docs.gigstack.io/llms.txt > Use this file to discover all available pages before exploring further. # Prepare an account approval > Requires a verified personal Firebase or MCP identity and current action authority. Team API/OAuth keys cannot prepare approvals. Reads and cancellation bind the creator and originating MCP credential/mode. Browser confirmation rechecks current authority, credential validity and relevant account state. Preparation never issues a credential or accepts terms. Persist a UUIDv4 operation_id before the first call. After a timeout, repeat only the exact action, scope and normalized payload with the same ID; it retrieves the existing intent. Changed input returns 409 operation_conflict. API actions require an empty payload; MCP creation requires a trimmed name and explicit livemode. Open review_url in the authenticated browser to review and confirm. The selected MCP team is initial context, not a user-access security ceiling. Select an authorized current team with the team query parameter for authentication context; preparation should use the same team as body.team_id. This does not alter the originating credential or mode. Membership actions require the current team owner. Prepare a transfer with payload {new_owner_id}, or an admin promotion/addition with payload {member_id}. The browser reviews the frozen target identity, current role and account-wide consequences. Team membership is shared across production and test: requested_modes is empty for these actions, not a sandbox-only promise. The old owner remains an administrator after transfer; billing-account ownership is unchanged. Membership execution returns no credentials. Ordinary editor/viewer changes and permissions-only patches retain their existing direct routes and authority. Administrator invitations require team.invitations.create_admin with team_id, or billing_account.invitations.create_admin with billing_account_id and no team_id. Payload must contain email and an explicit send_email boolean. Only the current canonical scope owner can approve; billing administrators or team owners do not substitute for the billing-account owner. Account-wide membership applies across live and test. To recover an existing unexpired pending admin invitation, supply existing_invitation_id and send_email:false. Review freezes the recipient address, scope, role, expiry and delivery choice. Completed means recorded, not emailed or joined. Read the receipt invitation through /users/me/account-invitations/{id} for delivery status. Missing canonical owner returns 409 canonical_owner_required and requires support recovery. Managed administrator creation uses managed_users.create_admin with team_id and an email/profile payload. Both canonical team and billing owners must be the initiating person. The first browser execution creates a disabled identity and its bootstrap records; a second fresh browser review is required to grant membership and activate it. No credentials or email are delivered. Unknown outcomes require reconcile, never another creation or activation attempt. Where owners differ, create a nonadmin managed user then use owner-reviewed promotion. Managed session actions use managed_users.issue_session or managed_users.revoke_sessions with team_id and exactly {user_id}. The current canonical owner of the billing account and every reachable team must be the initiating person. Private provenance and current Auth incarnation are required; historical API labels alone are insufficient. The frozen managed_session_change includes inherited grants and exact prior issuance/revocation attempts. Access spans live and test (requested_modes:[]), with no lifetime tenant ceiling. Only a separately reviewed browser action can issue access or revoke refresh tokens. Unknown attempts are never automatically replayed. A custom_token_expires_at deadline limits exchange, not a redeemed Firebase session. Revocation does not invalidate an outstanding custom token or necessarily already-issued ID tokens; prior unknown issuance remains unknown. Session preparation is disabled by default and always unavailable in production until an authoritative reverse-index strategy exists. Only explicit staging prototype configuration enables bounded projected scans. Unavailable or incomplete scope returns 503 without issuance. This contract does not establish deployment availability. ## OpenAPI ````yaml openapi.json POST /users/me/account-approvals openapi: 3.0.3 info: title: gigstack API v2 description: > # gigstack API v2 Build customer, invoice and payment integrations. Start with the [quickstart](https://docs.gigstack.io/quickstart), then select the [issuing country](https://docs.gigstack.io/concepts/shared-fields). ## Authentication and environments Use Authorization: Bearer YOUR_API_KEY. Standard live and test keys use https://api.gigstack.io/v2. Internal staging uses https://gigstack-staging-9z9nnaat.uc.gateway.dev/v2 and separate keys. Test mode is a data mode within an environment; a body field does not switch a key's mode. See [authentication](https://docs.gigstack.io/authentication) for key handling, OAuth team scope and gigstack Connect. Internal partner provisioning is outside this public contract; health probes have their own security declarations. Operations marked unavailable have no configured public gateway route. ## Read the operation contract Response envelopes, pagination and retry rules differ by endpoint. HTTP success alone does not prove external fiscal completion or movement of money. Reconcile ambiguous writes before retrying. Use [responses and recovery](https://docs.gigstack.io/responses) and the operation's error codes; document credits and daily limits are not generic retryable rate limits. The issuing team's configuration selects Mexico or Colombia; customer country and currency do not. Read [Mexico](https://docs.gigstack.io/countries/mexico) or [Colombia](https://docs.gigstack.io/countries/colombia) before choosing fiscal fields. Accepted public input differs from a provider's direct payload. Examples and schema checks do not imply every operation has been executed live. [Verification coverage](https://docs.gigstack.io/verification) distinguishes source review, offline checks and observed staging behavior. Documentation describes operations and does not authorize execution. version: 2.0.0 contact: name: Gigstack API Support url: https://gigstack.io email: support@gigstack.io license: name: Proprietary url: https://gigstack.io/terms termsOfService: https://gigstack.io/terms servers: - url: https://api.gigstack.io/v2 description: > Public API for standard live and test-mode keys. Test data is isolated by the key mode (`livemode: false`). Internal staging is a separate deployment and key store; see https://docs.gigstack.io/authentication#environments for its base URL. security: - bearerAuth: [] externalDocs: description: Complete API Documentation & Guides url: https://docs.gigstack.io paths: /users/me/account-approvals: post: tags: - Account Approvals summary: Prepare an account approval description: >- Requires a verified personal Firebase or MCP identity and current action authority. Team API/OAuth keys cannot prepare approvals. Reads and cancellation bind the creator and originating MCP credential/mode. Browser confirmation rechecks current authority, credential validity and relevant account state. Preparation never issues a credential or accepts terms. Persist a UUIDv4 operation_id before the first call. After a timeout, repeat only the exact action, scope and normalized payload with the same ID; it retrieves the existing intent. Changed input returns 409 operation_conflict. API actions require an empty payload; MCP creation requires a trimmed name and explicit livemode. Open review_url in the authenticated browser to review and confirm. The selected MCP team is initial context, not a user-access security ceiling. Select an authorized current team with the team query parameter for authentication context; preparation should use the same team as body.team_id. This does not alter the originating credential or mode. Membership actions require the current team owner. Prepare a transfer with payload {new_owner_id}, or an admin promotion/addition with payload {member_id}. The browser reviews the frozen target identity, current role and account-wide consequences. Team membership is shared across production and test: requested_modes is empty for these actions, not a sandbox-only promise. The old owner remains an administrator after transfer; billing-account ownership is unchanged. Membership execution returns no credentials. Ordinary editor/viewer changes and permissions-only patches retain their existing direct routes and authority. Administrator invitations require team.invitations.create_admin with team_id, or billing_account.invitations.create_admin with billing_account_id and no team_id. Payload must contain email and an explicit send_email boolean. Only the current canonical scope owner can approve; billing administrators or team owners do not substitute for the billing-account owner. Account-wide membership applies across live and test. To recover an existing unexpired pending admin invitation, supply existing_invitation_id and send_email:false. Review freezes the recipient address, scope, role, expiry and delivery choice. Completed means recorded, not emailed or joined. Read the receipt invitation through /users/me/account-invitations/{id} for delivery status. Missing canonical owner returns 409 canonical_owner_required and requires support recovery. Managed administrator creation uses managed_users.create_admin with team_id and an email/profile payload. Both canonical team and billing owners must be the initiating person. The first browser execution creates a disabled identity and its bootstrap records; a second fresh browser review is required to grant membership and activate it. No credentials or email are delivered. Unknown outcomes require reconcile, never another creation or activation attempt. Where owners differ, create a nonadmin managed user then use owner-reviewed promotion. Managed session actions use managed_users.issue_session or managed_users.revoke_sessions with team_id and exactly {user_id}. The current canonical owner of the billing account and every reachable team must be the initiating person. Private provenance and current Auth incarnation are required; historical API labels alone are insufficient. The frozen managed_session_change includes inherited grants and exact prior issuance/revocation attempts. Access spans live and test (requested_modes:[]), with no lifetime tenant ceiling. Only a separately reviewed browser action can issue access or revoke refresh tokens. Unknown attempts are never automatically replayed. A custom_token_expires_at deadline limits exchange, not a redeemed Firebase session. Revocation does not invalidate an outstanding custom token or necessarily already-issued ID tokens; prior unknown issuance remains unknown. Session preparation is disabled by default and always unavailable in production until an authoritative reverse-index strategy exists. Only explicit staging prototype configuration enables bounded projected scans. Unavailable or incomplete scope returns 503 without issuance. This contract does not establish deployment availability. operationId: prepareAccountApproval parameters: - $ref: '#/components/parameters/TeamParameter' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/AccountApprovalInput' - oneOf: - properties: action: enum: - api_keys.generate - api_keys.rotate payload: type: object additionalProperties: false properties: {} required: - team_id not: required: - billing_account_id - properties: action: enum: - mcp_tokens.create payload: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 64 livemode: type: boolean required: - name - livemode required: - team_id not: required: - billing_account_id - properties: action: enum: - team.ownership.transfer payload: type: object additionalProperties: false properties: new_owner_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - new_owner_id required: - team_id not: required: - billing_account_id - properties: action: enum: - team.members.promote_admin - team.members.add_admin payload: type: object additionalProperties: false properties: member_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - member_id required: - team_id not: required: - billing_account_id - required: - team_id not: required: - billing_account_id properties: action: enum: - team.invitations.create_admin payload: type: object additionalProperties: false properties: email: type: string maxLength: 320 format: email send_email: type: boolean existing_invitation_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - email - send_email not: required: - existing_invitation_id properties: send_email: enum: - true - required: - billing_account_id not: required: - team_id properties: action: enum: - billing_account.invitations.create_admin payload: type: object additionalProperties: false properties: email: type: string maxLength: 320 format: email send_email: type: boolean existing_invitation_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - email - send_email not: required: - existing_invitation_id properties: send_email: enum: - true - required: - team_id not: required: - billing_account_id properties: action: enum: - managed_users.create_admin payload: type: object additionalProperties: false properties: email: type: string maxLength: 320 format: email first_name: type: string nullable: true maxLength: 100 last_name: type: string nullable: true maxLength: 100 phone: type: string nullable: true pattern: ^\+[1-9]\d{7,14}$ company_role: type: string nullable: true maxLength: 100 address: type: object additionalProperties: false properties: country: type: string nullable: true maxLength: 250 street: type: string nullable: true maxLength: 250 zip: type: string nullable: true maxLength: 250 city: type: string nullable: true maxLength: 250 state: type: string nullable: true maxLength: 250 exterior: type: string nullable: true maxLength: 250 municipality: type: string nullable: true maxLength: 250 neighborhood: type: string nullable: true maxLength: 250 nullable: true required: - email - required: - team_id not: required: - billing_account_id properties: action: enum: - managed_users.issue_session - managed_users.revoke_sessions payload: type: object additionalProperties: false properties: user_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - user_id examples: apiKeys: value: operation_id: 00000000-0000-4000-8000-000000000001 action: api_keys.generate team_id: team_example payload: {} mcpToken: value: operation_id: 00000000-0000-4000-8000-000000000001 action: mcp_tokens.create team_id: team_example payload: name: Local agent livemode: false transferOwnership: value: operation_id: 00000000-0000-4000-8000-000000000002 action: team.ownership.transfer team_id: team_example payload: new_owner_id: user_example promoteAdmin: value: operation_id: 00000000-0000-4000-8000-000000000003 action: team.members.promote_admin team_id: team_example payload: member_id: user_example teamAdminInvitation: value: operation_id: 00000000-0000-4000-8000-000000000004 action: team.invitations.create_admin team_id: team_example payload: email: member@example.com send_email: false billingAdminInvitation: value: operation_id: 00000000-0000-4000-8000-000000000005 action: billing_account.invitations.create_admin billing_account_id: billing_example payload: email: member@example.com send_email: true recoverAdminInvitation: value: operation_id: 00000000-0000-4000-8000-000000000006 action: team.invitations.create_admin team_id: team_example payload: email: member@example.com send_email: false existing_invitation_id: inv_example managedSession: value: operation_id: 00000000-0000-4000-8000-000000000007 action: managed_users.issue_session team_id: team_example payload: user_id: managed_example revokeManagedSessions: value: operation_id: 00000000-0000-4000-8000-000000000008 action: managed_users.revoke_sessions team_id: team_example payload: user_id: managed_example required: true responses: '200': description: >- Safe approval state only. Cache-Control: no-store. Preparation is not issuance; GET and cancellation never return secrets or challenges. headers: Cache-Control: schema: type: string enum: - no-store content: application/json: schema: type: object additionalProperties: false properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/AccountApproval' timestamp: type: number required: - success - data - timestamp example: success: true data: id: >- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa operation_id: 00000000-0000-4000-8000-000000000001 action: api_keys.generate team: id: team_example legal_name: null tax_id: null billing_account_id: billing_example payload: {} requested_modes: - true - false effect_scope: team_credentials status: pending created_at: 1700000000000 expires_at: 1700000600000 completed_at: null review_url: >- https://app.gigstack.pro/account/approvals/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa can_cancel: true disclosure_version: credential-approval-v1 existing_key_ids: [] terms: null receipt: null error: null membership_change: null invitation_change: null managed_identity_change: null managed_identity_execution: null managed_session_change: null managed_session_execution: null timestamp: 1700000000000 '400': description: Invalid input, unknown fields, or action-specific payload mismatch. '401': description: Verified personal identity required. '403': description: >- Current authority, origin credential and mode, or enabled account checks failed. '404': description: Approval or account not found in authorized scope. '409': description: >- operation_conflict, changed account state, expired/cancelled approval, or active key conflict. '500': description: >- Preparation or state read failed. Preserve the operation ID and exact input; do not generate a replacement as an automatic retry. '503': description: >- managed_session_scope_unavailable: the strategy is disabled or production is unsupported. managed_session_scope_limit: a staging limit+1 scan detected incomplete scope. No session is issued; do not retry with new operation IDs. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: parameters: TeamParameter: name: team in: query required: false schema: type: string description: > **gigstack Connect:** Target team ID for multi-team access. Requires gigstack Connect enabled on your team and shared billing account. Also requires the `multipleIssuerAccounts` feature on your plan. Requests targeting a team other than the one your API key belongs to return `403` without it. Only API keys can use it: an OAuth access token sent with another team's id is rejected with `403 Team mismatch with OAuth token`. **Optional — omit it entirely** unless you are acting on another team. It deliberately carries no example value so generated snippets do not emit `?team=undefined`; when the parameter is absent, the team is derived from your API key. **Example:** `?team=team_xyz789` schemas: AccountApprovalInput: type: object additionalProperties: false required: - operation_id - action - payload properties: operation_id: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ action: type: string enum: - api_keys.create_scoped - api_keys.rotate_scoped - api_keys.generate - api_keys.rotate - mcp_tokens.create - team.ownership.transfer - team.members.promote_admin - team.members.add_admin - team.invitations.create_admin - billing_account.invitations.create_admin - managed_users.create_admin - managed_users.issue_session - managed_users.revoke_sessions team_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ billing_account_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ payload: type: object additionalProperties: false properties: first_name: type: string nullable: true maxLength: 100 last_name: type: string nullable: true maxLength: 100 phone: type: string nullable: true pattern: ^\+[1-9]\d{7,14}$ company_role: type: string nullable: true maxLength: 100 address: type: object additionalProperties: false properties: country: type: string nullable: true maxLength: 250 street: type: string nullable: true maxLength: 250 zip: type: string nullable: true maxLength: 250 city: type: string nullable: true maxLength: 250 state: type: string nullable: true maxLength: 250 exterior: type: string nullable: true maxLength: 250 municipality: type: string nullable: true maxLength: 250 neighborhood: type: string nullable: true maxLength: 250 nullable: true email: type: string maxLength: 320 format: email send_email: type: boolean existing_invitation_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ billing_account_id: type: string team_ids: type: array items: type: string maxItems: 100 action_ids: type: array items: type: string maxItems: 200 manager_user_ids: type: array items: type: string maxItems: 100 expires_at: type: integer nullable: true key_id: type: string overlap_seconds: type: integer minimum: 0 maximum: 86400 name: type: string minLength: 1 maxLength: 64 livemode: type: boolean new_owner_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ user_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ member_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ AccountApproval: type: object additionalProperties: false properties: id: type: string pattern: ^[a-f0-9]{64}$ operation_id: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ action: type: string enum: - api_keys.generate - api_keys.rotate - mcp_tokens.create - team.ownership.transfer - team.members.promote_admin - team.members.add_admin - team.invitations.create_admin - billing_account.invitations.create_admin - managed_users.create_admin - managed_users.issue_session - managed_users.revoke_sessions - api_keys.create_scoped - api_keys.rotate_scoped team: type: object additionalProperties: false properties: id: type: string legal_name: type: string nullable: true tax_id: type: string nullable: true required: - id - legal_name - tax_id nullable: true billing_account_id: type: string payload: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 64 livemode: type: boolean new_owner_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ member_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ email: type: string send_email: type: boolean existing_invitation_id: type: string first_name: type: string nullable: true maxLength: 100 last_name: type: string nullable: true maxLength: 100 phone: type: string nullable: true pattern: ^\+[1-9]\d{7,14}$ company_role: type: string nullable: true maxLength: 100 address: type: object additionalProperties: false properties: country: type: string nullable: true maxLength: 250 street: type: string nullable: true maxLength: 250 zip: type: string nullable: true maxLength: 250 city: type: string nullable: true maxLength: 250 state: type: string nullable: true maxLength: 250 exterior: type: string nullable: true maxLength: 250 municipality: type: string nullable: true maxLength: 250 neighborhood: type: string nullable: true maxLength: 250 nullable: true user_id: type: string billing_account_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ team_ids: type: array items: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ minItems: 1 maxItems: 100 action_ids: type: array items: type: string maxLength: 128 minItems: 1 maxItems: 200 expires_at: type: integer manager_user_ids: type: array items: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ maxItems: 100 key_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ overlap_seconds: type: integer minimum: 0 maximum: 86400 requested_modes: type: array items: type: boolean effect_scope: type: string enum: - team_credentials - user_access - team_membership - billing_account_membership - managed_identity - managed_session - scoped_api_key status: type: string enum: - pending - completed - cancelled - expired - invalidated - processing - unknown - failed - activation_required created_at: type: number expires_at: type: number completed_at: type: number nullable: true review_url: type: string format: uri can_cancel: type: boolean disclosure_version: type: string enum: - credential-approval-v1 - membership-approval-v1 - invitation-approval-v1 - managed-identity-v1 - managed-session-v1 existing_key_ids: type: array items: type: string terms: type: object additionalProperties: false properties: url: type: string format: uri acceptance_required: type: boolean enum: - true required: - url - acceptance_required nullable: true receipt: type: object additionalProperties: false properties: keys: type: array items: type: object additionalProperties: false properties: key_id: type: string type: type: string enum: - api - mcp livemode: type: boolean required: - key_id - type - livemode revoked_count: type: integer minimum: 0 membership: type: object additionalProperties: false properties: action: type: string enum: - team.ownership.transfer - team.members.promote_admin - team.members.add_admin member_id: type: string owner_id: type: string previous_owner_id: type: string role: type: string enum: - admin is_owner: type: boolean added: type: boolean required: - action - member_id - owner_id - previous_owner_id - role - is_owner - added nullable: true invitation: type: object additionalProperties: false properties: id: type: string type: type: string enum: - team - billingAccount team_id: type: string nullable: true billing_account_id: type: string email: type: string role: type: string enum: - admin expires_at: type: number approval_id: type: string required: - id - type - team_id - billing_account_id - email - role - expires_at - approval_id nullable: true managed_identity: type: object additionalProperties: false properties: user_id: type: string team_id: type: string billing_account_id: type: string role: type: string enum: - admin auth_state: type: string enum: - enabled membership_granted: type: boolean enum: - true required: - user_id - team_id - billing_account_id - role - auth_state - membership_granted nullable: true managed_session: type: object additionalProperties: false properties: user_id: type: string approval_id: type: string action: type: string enum: - managed_users.issue_session - managed_users.revoke_sessions custom_token_expires_at: type: number nullable: true description: >- Custom-token exchange deadline in epoch milliseconds, not the expiry of a redeemed Firebase session. Null for revocation. session_expiration: type: string enum: - not_bounded_by_custom_token revocation_scope: type: string enum: - refresh_tokens_only - null nullable: true required: - user_id - approval_id - action - custom_token_expires_at - session_expiration - revocation_scope nullable: true required: - keys - revoked_count - membership - invitation - managed_identity - managed_session nullable: true error: type: object additionalProperties: false properties: code: type: string message: type: string retryable: type: boolean enum: - false required: - code - message - retryable nullable: true membership_change: type: object additionalProperties: false properties: target: type: object additionalProperties: false properties: id: type: string email: type: string nullable: true display_name: type: string nullable: true required: - id - email - display_name previous_owner_id: type: string previous_role: type: string enum: - admin - editor - viewer - blocked - null nullable: true new_role: type: string enum: - admin transfers_ownership: type: boolean billing_ownership_changes: type: boolean enum: - false hidden_member: type: boolean enum: - false required: - target - previous_owner_id - previous_role - new_role - transfers_ownership - billing_ownership_changes - hidden_member nullable: true invitation_change: type: object additionalProperties: false properties: id: type: string type: type: string enum: - team - billingAccount email: type: string role: type: string enum: - admin team_id: type: string nullable: true billing_account_id: type: string billing_account_name: type: string nullable: true inviter: type: object additionalProperties: false properties: id: type: string email: type: string nullable: true display_name: type: string nullable: true required: - id - email - display_name send_email: type: boolean expires_at: type: number existing_invitation: type: boolean prior_delivery_status: type: string nullable: true required: - id - type - email - role - team_id - billing_account_id - billing_account_name - inviter - send_email - expires_at - existing_invitation - prior_delivery_status nullable: true managed_identity_change: type: object additionalProperties: false properties: user_id: type: string email: type: string profile: type: object additionalProperties: false properties: first_name: type: string nullable: true maxLength: 100 last_name: type: string nullable: true maxLength: 100 phone: type: string nullable: true pattern: ^\+[1-9]\d{7,14}$ company_role: type: string nullable: true maxLength: 100 address: type: object additionalProperties: false properties: country: type: string nullable: true maxLength: 250 street: type: string nullable: true maxLength: 250 zip: type: string nullable: true maxLength: 250 city: type: string nullable: true maxLength: 250 state: type: string nullable: true maxLength: 250 exterior: type: string nullable: true maxLength: 250 municipality: type: string nullable: true maxLength: 250 neighborhood: type: string nullable: true maxLength: 250 nullable: true team_id: type: string billing_account_id: type: string role: type: string enum: - admin auto_join: type: boolean enum: - true credential_delivery: type: string enum: - none initial_auth_state: type: string enum: - disabled bootstrap_effects: type: array items: type: string enum: - profile_initialization - membership_usage_initialization - support_identity_claims minItems: 3 maxItems: 3 required: - user_id - email - profile - team_id - billing_account_id - role - auto_join - credential_delivery - initial_auth_state - bootstrap_effects nullable: true managed_identity_execution: type: object additionalProperties: false properties: phase: type: string enum: - creating - activation_required - activating - complete - failed auth_state: type: string enum: - unknown - disabled - enabled membership_granted: type: boolean started_at: type: number updated_at: type: number error_code: type: string nullable: true required: - phase - auth_state - membership_granted - started_at - updated_at - error_code nullable: true managed_session_change: type: object additionalProperties: false properties: user_id: type: string email: type: string auth_creation_time: type: string billing_account_id: type: string teams: type: array items: type: object additionalProperties: false properties: id: type: string role: type: string description: >- Current access, including inherited billing_account_admin and master_team_billing_access. required: - id - role billing_accounts: type: array items: type: object additionalProperties: false properties: id: type: string role: type: string required: - id - role delivery: type: string enum: - browser_once - none session_scope: type: string enum: - firebase_identity prior_attempts: type: array items: type: object additionalProperties: false properties: approval_id: type: string action: type: string enum: - managed_users.issue_session - managed_users.revoke_sessions phase: type: string enum: - attempting - issued - revoked - unknown attempted_at: type: number custom_token_expires_at: type: number nullable: true description: >- Custom-token exchange deadline in epoch milliseconds, not the expiry of a redeemed Firebase session. Null for revocation. required: - approval_id - action - phase - attempted_at - custom_token_expires_at required: - user_id - email - auth_creation_time - billing_account_id - teams - billing_accounts - delivery - session_scope - prior_attempts nullable: true managed_session_execution: type: object additionalProperties: false properties: phase: type: string enum: - attempting - issued - revoked - unknown attempted_at: type: number custom_token_expires_at: type: number nullable: true description: >- Custom-token exchange deadline in epoch milliseconds, not the expiry of a redeemed Firebase session. Null for revocation. delivery: type: string enum: - not_observable - none required: - phase - attempted_at - custom_token_expires_at - delivery nullable: true scoped_key_change: type: object additionalProperties: false required: - name - livemode - billing_account_id - team_ids - action_ids - expires_at - manager_user_ids - action - previous_key_id - overlap_seconds - previous_revoke_at - unrelated_keys_affected - secret_disclosure properties: name: type: string minLength: 1 maxLength: 64 livemode: type: boolean billing_account_id: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ team_ids: type: array items: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ minItems: 1 maxItems: 100 action_ids: type: array items: type: string maxLength: 128 minItems: 1 maxItems: 200 expires_at: type: integer manager_user_ids: type: array items: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ maxItems: 100 action: type: string enum: - create - rotate previous_key_id: type: string nullable: true overlap_seconds: type: integer minimum: 0 maximum: 86400 previous_revoke_at: type: integer minimum: 0 nullable: true unrelated_keys_affected: type: boolean enum: - false secret_disclosure: type: string enum: - once nullable: true required: - id - operation_id - action - team - billing_account_id - payload - requested_modes - effect_scope - status - created_at - expires_at - completed_at - review_url - can_cancel - disclosure_version - existing_key_ids - terms - receipt - error - membership_change - invitation_change - managed_identity_change - managed_identity_execution - managed_session_change - managed_session_execution ErrorResponse: allOf: - $ref: '#/components/schemas/StandardErrorResponse' description: Standardized error envelope. example: success: false error: code: invalid_request_body message: An error occurred timestamp: 1767225600000 StandardErrorResponse: type: object description: > Standardized error envelope emitted by `sendErrorResponse` and its helpers (`sendValidationError`, `sendNotFoundError`, `sendUnauthorizedError`, `sendForbiddenError`, `sendConflictError`, `sendBadRequestError`, `sendInternalServerError`). required: - success - error - timestamp properties: success: type: boolean enum: - false example: false error: type: object required: - code - message properties: code: type: string description: > Stable machine-readable code. Values emitted by the shared helpers: `unauthorized`, `forbidden`, `invalid_token`, `validation_failed`, `invalid_request_body`, `missing_required_field`, `invalid_field_value`, `resource_not_found`, `resource_already_exists`, `resource_conflict`, `business_rule_violation`, `operation_not_allowed`, `insufficient_permissions`, `external_service_error`, `payment_processor_error`, `cfdi_service_error`, `internal_server_error`, `service_unavailable`, `rate_limit_exceeded`, `database_error`, `data_integrity_error`, `file_not_found`, `file_upload_error`, `invalid_file_format`. Individual handlers may emit additional endpoint-specific codes, documented per operation. example: validation_failed message: type: string example: Request validation failed details: oneOf: - type: string - type: array items: type: string description: > Present only when the handler supplies detail. Validation failures emit an array of `": "` strings. example: - 'currency: Field is required' timestamp: type: integer format: int64 description: Server time in epoch milliseconds. example: 1767225600000 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > **Authentication Method:** HTTP Bearer token. The runtime requires the literal `Bearer ` prefix — a bare token in the `Authorization` header is rejected with `401 unauthorized`. **Header Format:** `Authorization: Bearer YOUR_API_KEY` Your API key is a JWT. Live keys operate on live data (`livemode: true`); test keys operate on isolated test data (`livemode: false`). **Get your key at:** [app.gigstack.pro/settings?tab=api](https://app.gigstack.pro/settings?tab=api) **Errors:** credential failures are answered by the authentication layer with a raw `{ "message": … }` body, not the standardized envelope — `401` for a missing, malformed or expired token, `403` for a revoked key or a plan without API access. See the `Unauthorized` and `AuthForbidden` responses. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.