openapi: 3.0.3
info:
  title: Authentication Service API
  description: "Issues and verifies the JWT access tokens used across the UpStart Commerce\nplatform — for shoppers browsing a storefront, for staff using management\ntools, and for the services that trust those tokens.\n\nWhich half you are building for changes what you do with a token:\n\n- **Consumer traffic** — storefronts, apps. Verify the signature locally and\n  read the claims. No call back to this service, and no permission lookup.\n- **Management traffic** — admin and back-office tools. Verify the same way,\n  then resolve authorization against `profile-permissions-svc`. Because the\n  token carries role *references* rather than a permission list, granting a\n  role takes effect immediately, without reissuing anyone's token.\n\n## Verifying a token\n\nFetch the signing keys from `/.well-known/jwks.json`. It needs no credentials,\nsends CORS headers, and is cacheable for 24 hours — fetch once, cache, and\nrefetch only when you meet a `kid` you do not recognise.\n\nVerify `RS256`, then check that `exp` is in the future and that `iss` matches the\nissuer configured for the environment you are calling — `auth-svc` by default,\nbut it is a configurable value, so read it from your own config rather than\nhard-coding the literal. The claims you get back:\n\n| Claim | Meaning |\n|---|---|\n| `sub` | User id |\n| `type` | `consumer` or `management` — which model above applies. Lower-case on the wire; compare case-sensitively. |\n| `tenant` | The tenant this session is active for |\n| `roles` | Global and tenant-level role names |\n| `siteRoles` | Site id → role names, for site-scoped access |\n| `iat` / `exp` | Issued-at and expiry, as Unix timestamps |\n| `iss` | The issuer configured for the environment. `auth-svc` unless overridden. |\n\nTokens are deliberately thin (~500 bytes). Everything above is in the token;\nanything not in the token needs a lookup.\n\n## Getting a token\n\nAnonymous browsing needs no credentials:\n\n    curl -X POST https://api.upstartcommerce.com/api/v1/auth/guest \\\n      -H 'x-upstart-tenant: your-tenant'\n\nSigning a user in returns an access and refresh token:\n\n    curl -X POST https://api.upstartcommerce.com/api/v1/auth/login \\\n      -H 'x-upstart-tenant: your-tenant' \\\n      -H 'Content-Type: application/json' \\\n      -d '{\"username\":\"user@example.com\",\"password\":\"…\"}'\n\nThen send it on every call:\n\n    Authorization: Bearer <accessToken>\n\n**Login does not always return tokens.** If the account requires a second\nfactor you get `mfaRequired: true`, an `mfaChallengeId`, the delivery method, a\nmasked destination and the challenge's own expiry — and no tokens. Finish with\n`/auth/mfa/verify`, or get a fresh code from `/auth/mfa/resend`. Treat it as a\nbranch in your login flow, not an error.\n\n## Keeping a session alive\n\nAccess tokens last one hour and refresh tokens seven days by default, both\nenvironment-configurable — read `expiresIn` from the response rather than\nhard-coding either.\n\nRefresh **rotates**. `/auth/refresh` returns a new pair and invalidates the one\nyou presented, so persist the new refresh token every time. `/auth/logout`\nrevokes it.\n\nThere is also a ceiling on total session age — 30 days by default, and likewise\nconfigurable — that refreshing cannot extend. When you reach it the error is\n`session_expired` and the only way forward is a full login, so handle it\ndistinctly from an ordinary expired access token.\n\n## Tenant and site context\n\nThe active tenant travels **in the token**, as the `tenant` claim, so a verified\ntoken already tells a service which tenant it is acting for.\n\nThe `x-upstart-tenant` header is how a caller *selects* that tenant when the\nuser belongs to more than one. `/auth/tenants` lists what the session can reach\n— use it to drive a tenant switcher — and `/auth/refresh` moves an existing\nsession to a different tenant without asking for credentials again.\n`/auth/sites` does the same for sites within the active tenant.\n\n## When calls fail\n\nErrors carry a machine-readable `error`, a human `message` and a `code`.\
    \ The\nones worth branching on:\n\n| `error` | What to do |\n|---|---|\n| `unauthorized` | Bad credentials or a bad token. Re-authenticate. |\n| `session_expired` | Session ceiling reached. Full login; refresh will not help. |\n| `tenant_required` | Multi-tenant user, no tenant chosen. Send `x-upstart-tenant`. |\n| `unauthorized_tenant` / `unauthorized_site` | Authenticated, but not for that scope. |\n| `site_required` / `no_authorized_sites` | Site context missing, or none available to this user. |\n| `account_not_verified` | Real account, unverified email or phone. |\n| `account_locked` | Too many failed attempts. Temporary. |\n| `rate_limited` | Back off and retry. |\n| `invalid_request` | Malformed body or a missing field. |\n"
  version: 1.0.0
  contact:
    name: UpStart Commerce, Inc.
    email: support@upstartcommerce.com
    url: https://upstartcommerce.atlassian.net/servicedesk/customer/portal/1
  license:
    name: Proprietary
servers:
- url: https://api.upstartcommerce.com
  description: Production
tags:
- name: Authentication
  description: Sign in, issue and rotate tokens, and discover the tenants and sites a session can use.
paths:
  /.well-known/jwks.json:
    get:
      operationId: getJwks
      summary: Get the JSON Web Key Set used to verify tokens
      description: 'Public keys for verifying access-token signatures. Requires no credentials, sends CORS headers, and is safe to cache — responses carry `Cache-Control: max-age=86400`. Fetch it once, cache it, and refetch on an unrecognised `kid` rather than per request.'
      tags:
      - Authentication
      responses:
        '200':
          description: The key set currently valid for verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwksResponse'
        '500':
          description: No signing key is available. Only occurs if the service is configured with a symmetric algorithm, which cannot expose a public key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/auth/guest:
    post:
      operationId: guestToken
      summary: Issue or refresh an anonymous consumer token
      description: "Issues a short-lived JWT access token for anonymous browsing without credentials.\n\nThe endpoint serves both new and returning guests through a single call:\n\n- **No cookie** (new visitor): creates a new guest session, returns access token,\n  sets `guest_session` HttpOnly cookie.\n- **Valid cookie** (returning visitor): rotates the cookie atomically, returns a\n  new access token with the same stable session identity.\n- **Unknown/expired cookie** (reuse conflict or expiry): silently creates a new\n  session (logs a warning server-side), returns access token, sets new cookie.\n\n**Access token** — short-lived JWT (1 hour), hold in JS memory, send on every API call.\n\n**Guest session cookie** — long-lived opaque UUID (30 days by default), stored as\n`HttpOnly; Secure; SameSite=Strict`, invisible to JavaScript.\n\n**JWT claims**: `sub = \"guest:<stableSessionId>\"`, `type = \"consumer\"`, `roles = []`,\n`tenant` from the `x-upstart-tenant` header. The `stableSessionId` never changes for the\nlifetime of the guest session and can be used as a consistent identity key by downstream\nservices (e.g. cart-svc).\n\n**Rate limiting**: requests are rate-limited by client IP (`guest:<ip>`).\n"
      tags:
      - Authentication
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: Cookie
        in: header
        description: Optional `guest_session` cookie from a previous call
        schema:
          type: string
        example: guest_session=3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: 'Guest access token issued. The `guest_session` cookie in the response replaces

            any previously presented cookie — always store the latest value.

            '
          headers:
            Set-Cookie:
              description: 'Rotated guest session cookie. Always `HttpOnly; Secure; SameSite=Strict`.

                '
              schema:
                type: string
              example: guest_session=7fd113e1-1d30-48d2-88e0-50ef573ecef0; Max-Age=2592000; Secure; HTTPOnly; SameSite=Strict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuestTokenResponse'
              example:
                accessToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                expiresIn: 3600
                tokenType: Bearer
        '400':
          description: Missing required `x-upstart-tenant` header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: tenant_required
                message: x-upstart-tenant header is required
                code: BAD_REQUEST
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: rate_limited
                message: Too many guest token requests. Retry in 900s.
                code: RATE_LIMITED
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/auth/login:
    post:
      operationId: login
      summary: Authenticate user and issue tokens
      description: 'Validates user credentials and issues JWT access and refresh tokens.


        Tenant context is resolved in priority order:

        1. `Authorization: Bearer <guest-token>` — tenant extracted from the guest token''s `tenant` claim (preferred)

        2. `x-upstart-tenant` header — explicit tenant selection (fallback, deprecated)


        The guest token is issued by the `/api/v1/auth/guest` endpoint and carries the tenant

        (and site) context for the current browsing session. Clients should always present the

        guest token; the `x-upstart-tenant` header is retained for backwards compatibility only.


        The token includes `siteRoles` containing all sites the user can access.

        Site context is determined at runtime via the `x-upstart-site` header on

        subsequent API calls, not at login time.


        The response includes both an access token (short-lived, for API calls) and

        a refresh token (long-lived, for obtaining new access tokens).

        '
      tags:
      - Authentication
      parameters:
      - name: Authorization
        in: header
        description: 'Guest token issued by `/api/v1/auth/guest`, carrying tenant (and site) context for the session.

          The `tenant` claim is extracted and used as the active tenant for this login.

          Falls back to `x-upstart-tenant` if absent or if the token cannot be parsed.

          '
        schema:
          type: string
          pattern: ^Bearer .+$
        example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
      - $ref: '#/components/parameters/TenantHeader'
      requestBody:
        description: User credentials for authentication
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              consumerLogin:
                summary: Consumer login
                value:
                  username: customer@example.com
                  password: securePassword123
                  tokenType: consumer
              managementLogin:
                summary: Management login
                value:
                  username: admin@company.com
                  password: adminPassword456
                  tokenType: management
      responses:
        '200':
          description: 'Authentication result. Either:

            - Successful authentication with tokens (mfaRequired=false or absent)

            - MFA challenge required (mfaRequired=true)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
              examples:
                successfulLogin:
                  summary: Successful login (no MFA)
                  value:
                    mfaRequired: false
                    accessToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                    refreshToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                    expiresIn: 3600
                    tokenType: Bearer
                mfaRequired:
                  summary: MFA verification required
                  value:
                    mfaRequired: true
                    mfaChallengeId: ch_abc123xyz
                    mfaMethod: totp
                    mfaExpiresIn: 300
        '400':
          description: Bad request - invalid JSON, missing fields, or tenant selection required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidRequest:
                  summary: Invalid request body
                  value:
                    error: invalid_request
                    message: Failed to read request body
                    code: BAD_REQUEST
                tenantRequired:
                  summary: Tenant selection required
                  value:
                    error: tenant_required
                    message: Multiple tenants available; tenant selection required via x-upstart-tenant header
                    code: TENANT_REQUIRED
                invalidTokenType:
                  summary: Invalid token type
                  value:
                    error: invalid_request
                    message: Invalid token type. Must be 'consumer' or 'management'
                    code: BAD_REQUEST
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unauthorized
                message: Invalid username or password
                code: UNAUTHORIZED
        '403':
          description: Forbidden - unauthorized tenant or no authorized tenants
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorizedTenant:
                  summary: Unauthorized tenant
                  value:
                    error: unauthorized_tenant
                    message: 'User is not authorized for tenant: tenant-xyz'
                    code: UNAUTHORIZED_TENANT
                noAuthorizedTenants:
                  summary: No authorized tenants
                  value:
                    error: forbidden
                    message: User has no authorized tenants
                    code: FORBIDDEN
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/auth/logout:
    post:
      operationId: logout
      summary: Logout and revoke refresh token
      description: 'Revokes the provided refresh token, ending the user''s session.


        After logout:

        - The refresh token can no longer be used to obtain new access tokens

        - Existing access tokens remain valid until they expire (stateless validation)

        - For immediate access revocation, services should implement token blacklisting

        '
      tags:
      - Authentication
      requestBody:
        description: Refresh token to revoke
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogoutRequest'
            example:
              refreshToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
      responses:
        '204':
          description: Logout successful - refresh token revoked
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: invalid_request
                message: Failed to read request body
                code: BAD_REQUEST
        '401':
          description: Invalid or already revoked refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unauthorized
                message: Invalid or revoked refresh token
                code: UNAUTHORIZED
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/auth/mfa/resend:
    post:
      operationId: resendMfa
      summary: Resend SMS OTP code
      description: 'Resends the SMS OTP code for an existing MFA challenge.

        Only available for SMS MFA method.

        '
      tags:
      - Authentication
      requestBody:
        description: Challenge ID for resending OTP
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MfaResendRequest'
            example:
              challengeId: ch_abc123xyz
      responses:
        '200':
          description: OTP resent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaChallengeResponse'
              example:
                challengeId: ch_abc123xyz
                method: sms
                expiresIn: 300
                maskedPhoneNumber: '***1234'
        '400':
          description: Invalid request or not SMS MFA
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: invalid_request
                message: Resend only available for SMS MFA
                code: BAD_REQUEST
        '401':
          description: Challenge expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unauthorized
                message: MFA challenge has expired
                code: UNAUTHORIZED
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/auth/mfa/verify:
    post:
      operationId: verifyMfa
      summary: Verify MFA code and complete authentication
      description: 'Verifies the MFA code (TOTP, SMS OTP, or backup code) and completes the

        authentication process started by the login endpoint.


        Upon successful verification, returns access and refresh tokens.

        '
      tags:
      - Authentication
      requestBody:
        description: MFA verification details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MfaVerifyRequest'
            example:
              challengeId: ch_abc123xyz
              code: '123456'
      responses:
        '200':
          description: MFA verification successful - tokens issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
              example:
                accessToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                refreshToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                expiresIn: 3600
                tokenType: Bearer
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: invalid_request
                message: Challenge ID and code are required
                code: BAD_REQUEST
        '401':
          description: Invalid MFA code or challenge expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidCode:
                  summary: Invalid MFA code
                  value:
                    error: unauthorized
                    message: Invalid MFA code. 4 attempts remaining.
                    code: UNAUTHORIZED
                challengeExpired:
                  summary: Challenge expired
                  value:
                    error: unauthorized
                    message: MFA challenge has expired. Please login again.
                    code: UNAUTHORIZED
        '403':
          description: Account locked due to too many failed attempts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: forbidden
                message: Account locked due to too many failed MFA attempts
                code: FORBIDDEN
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/auth/refresh:
    post:
      operationId: refreshToken
      summary: Refresh access token
      description: 'Exchange a valid refresh token for a new access token and refresh token pair.


        **Token Rotation**: Each refresh operation issues a new refresh token and

        invalidates the previous one. This limits the window of exposure if a

        refresh token is compromised.


        **Tenant Switching**: Optionally switch to a different authorized tenant

        by including the `tenant` parameter. The new tenant must be in the user''s

        list of authorized tenants.

        '
      tags:
      - Authentication
      requestBody:
        description: Refresh token for obtaining new access token
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshRequest'
            examples:
              basicRefresh:
                summary: Basic token refresh
                value:
                  refreshToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
              refreshWithTenantSwitch:
                summary: Refresh with tenant switch
                value:
                  refreshToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                  tenant: tenant-456
      responses:
        '200':
          description: Token refresh successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
              example:
                accessToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                refreshToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                expiresIn: 3600
                tokenType: Bearer
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: invalid_request
                message: Failed to read request body
                code: BAD_REQUEST
        '401':
          description: Invalid, expired, or revoked refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidToken:
                  summary: Invalid token
                  value:
                    error: unauthorized
                    message: Invalid refresh token
                    code: UNAUTHORIZED
                expiredToken:
                  summary: Expired token
                  value:
                    error: unauthorized
                    message: Refresh token has expired
                    code: UNAUTHORIZED
                revokedToken:
                  summary: Revoked token
                  value:
                    error: unauthorized
                    message: Refresh token has been revoked
                    code: UNAUTHORIZED
        '403':
          description: Unauthorized tenant switch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unauthorized_tenant
                message: 'User is not authorized for tenant: tenant-xyz'
                code: UNAUTHORIZED_TENANT
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/auth/sites:
    get:
      operationId: getSites
      summary: Get available sites for current session
      description: 'Returns the current active site and list of all authorized sites

        for the user associated with the provided refresh token within the current tenant.


        Use this endpoint to populate a site switcher UI.


        **Authentication**: Provide the refresh token via either:

        - `Authorization: Bearer <refresh-token>` header

        - `refresh_token` query parameter

        '
      tags:
      - Authentication
      parameters:
      - name: Authorization
        in: header
        description: Bearer token containing the refresh token
        schema:
          type: string
          pattern: ^Bearer .+$
        example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
      - name: refresh_token
        in: query
        description: Alternative way to provide refresh token (if not using Authorization header)
        schema:
          type: string
        example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
      responses:
        '200':
          description: Site information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteInfoResponse'
              example:
                availableSites:
                - site-123
                - site-456
        '400':
          description: Refresh token not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: invalid_request
                message: Refresh token required via Authorization header or refresh_token query parameter
                code: BAD_REQUEST
        '401':
          description: Invalid or revoked refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unauthorized
                message: Invalid or revoked refresh token
                code: UNAUTHORIZED
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/auth/tenants:
    get:
      operationId: getTenants
      summary: Get available tenants for current session
      description: 'Returns the current active tenant and list of all authorized tenants

        for the user associated with the provided refresh token.


        Use this endpoint to populate a tenant switcher UI.


        **Authentication**: Provide the refresh token via either:

        - `Authorization: Bearer <refresh-token>` header

        - `refresh_token` query parameter

        '
      tags:
      - Authentication
      parameters:
      - name: Authorization
        in: header
        description: Bearer token containing the refresh token
        schema:
          type: string
          pattern: ^Bearer .+$
        example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
      - name: refresh_token
        in: query
        description: Alternative way to provide refresh token (if not using Authorization header)
        schema:
          type: string
        example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
      responses:
        '200':
          description: Tenant information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantInfoResponse'
              example:
                currentTenant: tenant-123
                availableTenants:
                - tenant-123
                - tenant-456
                - tenant-789
        '400':
          description: Refresh token not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: invalid_request
                message: Refresh token required via Authorization header or refresh_token query parameter
                code: BAD_REQUEST
        '401':
          description: Invalid or revoked refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unauthorized
                message: Invalid or revoked refresh token
                code: UNAUTHORIZED
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    TenantHeader:
      name: x-upstart-tenant
      in: header
      description: 'Tenant identifier for multi-tenant authentication.


        Required when user is authorized for multiple tenants.

        Optional when user has exactly one authorized tenant (auto-selected).

        '
      schema:
        type: string
      example: tenant-123
  schemas:
    AuthResponse:
      type: object
      description: Successful authentication response containing tokens
      required:
      - accessToken
      - refreshToken
      - expiresIn
      - tokenType
      properties:
        accessToken:
          type: string
          description: 'JWT access token for API authorization.


            Include in API requests as: `Authorization: Bearer <accessToken>`


            **Claims**:

            - `sub`: User ID (UUID)

            - `type`: Token type (consumer/management)

            - `roles`: List of role identifiers

            - `tenant`: Active tenant ID

            - `iat`: Issued at (Unix timestamp)

            - `exp`: Expiration (Unix timestamp)

            - `iss`: Issuer (auth-svc)

            '
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...
        refreshToken:
          type: string
          description: 'Refresh token for obtaining new access tokens.


            Store securely (e.g., httpOnly cookie or secure storage).

            Use with `/api/v1/auth/refresh` when access token expires.

            '
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...
        expiresIn:
          type: integer
          format: int64
          description: Access token validity duration in seconds
          example: 3600
        tokenType:
          type: string
          description: Token type (always "Bearer")
          example: Bearer
    ErrorResponse:
      type: object
      description: Standard error response format
      required:
      - error
      - message
      - code
      properties:
        error:
          type: string
          description: 'Error type identifier:

            - `invalid_request`: Malformed request or missing required fields

            - `unauthorized`: Invalid credentials or token

            - `account_not_verified`: Account exists but email/phone not verified

            - `session_expired`: Maximum session lifetime exceeded, full re-login required

            - `unauthorized_tenant`: User not authorized for requested tenant

            - `tenant_required`: Multi-tenant user must specify tenant

            - `unauthorized_site`: User not authorized for requested site

            - `site_required`: Site context required for this operation

            - `no_authorized_sites`: User has no authorized sites

            - `forbidden`: Access denied (e.g., no authorized tenants)

            - `rate_limited`: Too many requests, try again later

            - `account_locked`: Account temporarily locked due to failed attempts

            - `internal_error`: Server-side error

            '
          example: unauthorized
        message:
          type: string
          description: Human-readable error description
          example: Invalid username or password
        code:
          type: string
          description: HTTP status code name
          enum:
          - BAD_REQUEST
          - UNAUTHORIZED
          - UNAUTHORIZED_TENANT
          - TENANT_REQUIRED
          - FORBIDDEN
          - RATE_LIMITED
          - ACCOUNT_LOCKED
          - INTERNAL_SERVER_ERROR
          example: UNAUTHORIZED
    GuestTokenResponse:
      type: object
      description: 'Response from `POST /api/v1/auth/guest`. The access token is returned in the body

        (store in JS memory, send on every API call). The opaque session token is set as an

        `HttpOnly` cookie by the server and is never exposed in the response body.

        '
      required:
      - accessToken
      - expiresIn
      - tokenType
      properties:
        accessToken:
          type: string
          description: 'JWT access token for anonymous API calls.


            Include in requests as: `Authorization: Bearer <accessToken>`


            **Claims**:

            - `sub`: `guest:<stableSessionId>` — stable across session rotations

            - `type`: `consumer`

            - `roles`: `["customer.anonymous"]` by default (configurable via `guest-session.guestRoles`)

            - `tenant`: active tenant ID

            - `iat` / `exp` / `iss`: standard JWT fields

            '
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        expiresIn:
          type: integer
          format: int64
          description: Seconds until the access token expires
          example: 3600
        tokenType:
          type: string
          description: Token type (always "Bearer")
          example: Bearer
    JwkKey:
      description: A single public key in JWK form.
      type: object
      properties:
        kty:
          type: string
          description: Key type. Always `RSA` for this service.
          example: RSA
        kid:
          type: string
          description: Key id. Match this against the `kid` in the token header to pick the right key.
          example: auth-svc-2026-01
        use:
          type: string
          description: Intended use. `sig` — signature verification.
          example: sig
        alg:
          type: string
          description: Signing algorithm.
          example: RS256
        n:
          type: string
          description: RSA modulus, base64url encoded.
        e:
          type: string
          description: RSA public exponent, base64url encoded.
          example: AQAB
      required:
      - kty
      - kid
      - use
      - alg
      - n
      - e
    JwksResponse:
      description: A JSON Web Key Set — the public keys currently valid for verifying access tokens.
      type: object
      properties:
        keys:
          description: The active verification keys. Select by `kid`; expect more than one during a key rotation.
          type: array
          items:
            $ref: '#/components/schemas/JwkKey'
      required:
      - keys
    LoginRequest:
      type: object
      description: Request body for user authentication
      required:
      - username
      - password
      - tokenType
      properties:
        username:
          type: string
          description: User's username or email address
          example: user@example.com
        password:
          type: string
          format: password
          description: User's password
          example: securePassword123
        tokenType:
          type: string
          enum:
          - consumer
          - management
          description: 'Type of authentication session:

            - `consumer`: High-volume consumer traffic with fixed role mapping

            - `management`: Admin/management traffic with dynamic permission queries

            '
          example: consumer
    LoginResponse:
      type: object
      description: 'Login response that indicates either successful authentication or MFA requirement.


        When mfaRequired is false or absent: accessToken, refreshToken, expiresIn, tokenType are present

        When mfaRequired is true: mfaChallengeId, mfaMethod, mfaExpiresIn are present

        '
      required:
      - mfaRequired
      properties:
        mfaRequired:
          type: boolean
          description: Whether MFA verification is required before tokens are issued
          example: false
        accessToken:
          type: string
          description: JWT access token (present when mfaRequired is false)
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        refreshToken:
          type: string
          description: Refresh token (present when mfaRequired is false)
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        expiresIn:
          type: integer
          format: int64
          description: Access token validity in seconds (present when mfaRequired is false)
          example: 3600
        tokenType:
          type: string
          description: Token type, always "Bearer" (present when mfaRequired is false)
          example: Bearer
        mfaChallengeId:
          type: string
          description: MFA challenge ID for verification (present when mfaRequired is true)
          example: ch_abc123xyz
        mfaMethod:
          type: string
          enum:
          - totp
          - sms
          description: MFA method for verification (present when mfaRequired is true)
          example: totp
        mfaExpiresIn:
          type: integer
          format: int64
          description: Seconds until MFA challenge expires (present when mfaRequired is true)
          example: 300
        mfaMaskedPhoneNumber:
          type: string
          description: Masked phone number for SMS MFA (present when mfaMethod is sms)
          example: '***1234'
    LogoutRequest:
      type: object
      description: Request body for logout
      required:
      - refreshToken
      properties:
        refreshToken:
          type: string
          description: Refresh token to revoke
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    MfaChallengeResponse:
      type: object
      description: MFA challenge information
      required:
      - challengeId
      - method
      - expiresIn
      properties:
        challengeId:
          type: string
          description: Unique identifier for the MFA challenge
          example: ch_abc123xyz
        method:
          type: string
          enum:
          - totp
          - sms
          description: MFA method
          example: sms
        expiresIn:
          type: integer
          format: int64
          description: Seconds until challenge expires
          example: 300
        maskedPhoneNumber:
          type: string
          description: Masked phone number (for SMS only)
          example: '***1234'
    MfaResendRequest:
      type: object
      description: Request to resend SMS OTP code
      required:
      - challengeId
      properties:
        challengeId:
          type: string
          description: MFA challenge ID from login response
          example: ch_abc123xyz
    MfaVerifyRequest:
      type: object
      description: Request to verify MFA code and complete authentication
      required:
      - challengeId
      - code
      properties:
        challengeId:
          type: string
          description: MFA challenge ID from login response
          example: ch_abc123xyz
        code:
          type: string
          description: MFA verification code (TOTP, SMS OTP, or backup code)
          minLength: 6
          maxLength: 10
          example: '123456'
    RefreshRequest:
      type: object
      description: Request body for token refresh
      required:
      - refreshToken
      properties:
        refreshToken:
          type: string
          description: Valid refresh token from previous login or refresh
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        tenant:
          type: string
          description: 'Optional tenant to switch to during refresh.

            Must be in the user''s list of authorized tenants.

            '
          example: tenant-456
        site:
          type: string
          description: 'Optional site to switch to during refresh.

            Must be in the user''s list of authorized sites for the target tenant.

            '
          example: site-123
    SiteInfoResponse:
      type: object
      description: 'Information about user''s site access within current tenant.

        Site context is determined at runtime via the x-upstart-site header,

        not embedded in the token.

        '
      required:
      - availableSites
      properties:
        availableSites:
          type: array
          description: List of all sites the user is authorized to access within the current tenant
          items:
            type: string
          example:
          - site-123
          - site-456
    TenantInfoResponse:
      type: object
      description: Information about user's tenant access
      required:
      - currentTenant
      - availableTenants
      properties:
        currentTenant:
          type: string
          description: Currently active tenant for this session
          example: tenant-123
        availableTenants:
          type: array
          description: List of all tenants the user is authorized to access
          items:
            type: string
          example:
          - tenant-123
          - tenant-456
          - tenant-789
  responses:
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            tokenGenerationFailed:
              summary: Token generation failed
              value:
                error: internal_error
                message: Token generation failed
                code: INTERNAL_SERVER_ERROR
            serviceError:
              summary: Upstream service error
              value:
                error: internal_error
                message: Failed to communicate with authentication backend
                code: INTERNAL_SERVER_ERROR
