Choozle Authorization API

openapi: 3.2.0
info:
  title: Choozle Outbound Reporting Authorization API
  description: REST API for retrieving Choozle advertising account structure (accounts, campaigns, ad groups) and daily campaign performance reports.
  version: 1.0.0
  contact:
    name: Choozle Support
    url: https://help.choozle.com/
  termsOfService: https://choozle.com/terms-of-service/
servers:
- url: https://app.choozle.com/api
  description: Choozle production API
security:
- tokenHeader: []
tags:
- name: Authorization
  description: Token exchange.
paths:
  /auth:
    post:
      operationId: getAuthorizationToken
      summary: Get Authorization Token
      description: 'Authenticates an API-only user and returns a token for use in subsequent API requests. Tokens expire two hours after creation, at which point a new one must be generated by re-authenticating.


        Parameters must be sent in the request BODY (not headers) with `Content-Type: application/x-www-form-urlencoded`. The signature is an HMAC-SHA256 digest, in lowercase hex, of the concatenation of the submitted `email` and `timestamp` values, keyed with the account''s API private key.'
      tags:
      - Authorization
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AuthorizationRequest'
      responses:
        '200':
          description: Successful authentication; returns a token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationToken'
              example:
                token: c0a011497e5d2f974d05582f33c793688853be6b18a5b68136f41946d612347e
        '401':
          description: Request incomplete — missing or invalid email, timestamp or signature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Request incomplete
components:
  schemas:
    Error:
      type: object
      description: 'Choozle''s error envelope. A single `error` string; not RFC 9457 problem+json.

        '
      properties:
        error:
          type: string
          example: Unauthorized - No Token Found in request
    AuthorizationRequest:
      type: object
      description: HMAC-signed credentials exchanged for a two-hour API token.
      required:
      - email
      - timestamp
      - signature
      properties:
        email:
          type: string
          format: email
          description: The API profile user's email.
          example: user+api@example.com
        timestamp:
          type: string
          format: date-time
          description: 'Current datetime in ISO 8601 format, e.g. 2015-05-04T11:34:02-06:00. Must be within five minutes of the server''s current time.

            '
          example: '2015-05-04T11:34:02-06:00'
        signature:
          type: string
          description: 'Signature used to verify your private key. The data to hash is the concatenation of the submitted email and timestamp parameters, hashed with HMAC-SHA256 using your API private key as the hash key. Must be lowercase hex — not uppercase hex and not base64.

            '
          example: REDACTED_EXAMPLE_SIGNATURE_HEX
    AuthorizationToken:
      type: object
      description: Token returned after successful authentication.
      properties:
        token:
          type: string
          description: 'Authentication token to be included in the header of all subsequent API requests. Tokens expire two hours after creation, at which point a new one must be generated by re-authenticating.

            '
  securitySchemes:
    tokenHeader:
      type: apiKey
      in: header
      name: token
      description: 'Authentication token generated from the /api/auth endpoint. Valid for two hours from creation. Pass the token value as the `token` request header on every reporting call.

        '
externalDocs:
  description: Choozle API Docs (apiDoc)
  url: https://app.choozle.com/apidoc/