openapi: 3.1.0
info:
  title: HQ API
  description: Internal API for resolving user and account identifiers across Loop products.
  version: "v1"
servers:
  - url: https://hq.loopreturns.com
tags:
  - name: Organizations
security:
  - oauth2: []
paths:
  /api/v1/organizations/{auth0_org_id}:
    get:
      summary: Get Organization
      description: Retrieve internal identifiers for an organization across all Loop products.
      operationId: getOrganization
      tags:
        - Organizations
      parameters:
        - name: auth0_org_id
          in: path
          required: true
          description: The Auth0 organization ID.
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: |
        Auth0 Client Credentials authentication.

        Authorized clients in Auth0 must request a token from the token endpoint, passing
        your `client_id`, `client_secret`, `grant_type: client_credentials`, and
        `audience: https://hq.loopreturns.com/api`.
        Include the returned access token as a Bearer token on all requests.
      flows:
        clientCredentials:
          tokenUrl: https://loopreturns-orgs-production.us.auth0.com/oauth/token
          scopes: {}
  schemas:
    OrganizationResponse:
      type: object
      properties:
        auth0:
          type: object
          properties:
            org_id:
              type: string
              description: The Auth0 organization ID.
              example: org_abc123
        billing:
          type: object
          nullable: true
          properties:
            ordway_customer_id:
              type: string
              nullable: true
              description: The Ordway customer ID for this organization.
              example: ABC
            ordway_parent_id:
              type: string
              nullable: true
              description: The Ordway parent customer ID, if this org belongs to a parent account.
              example: null
            ordway_highest_parent_id:
              type: string
              nullable: true
              description: The highest Ordway parent customer ID in the account hierarchy.
              example: null
        products:
          type: object
          description: Per-product details for this organization.
          properties:
            tracking:
              $ref: "#/components/schemas/ProductEntry"
            returns:
              $ref: "#/components/schemas/ProductEntry"
            boost:
              $ref: "#/components/schemas/ProductEntry"
    ProductEntry:
      type: object
      properties:
        shop_id:
          type: string
          nullable: true
          description: The shop ID for this product, or null if not provisioned.
          example: "123"
        active:
          type: boolean
          description: Whether this product is active for the organization.
          example: true
    UnauthorizedResponse:
      type: object
      properties:
        message:
          type: string
          example: Unauthorized
    NotFoundResponse:
      type: object
      properties:
        message:
          type: string
          example: Organization not found