openapi: 3.0.3
info:
  title: Calm Partner Authentication API
  description: 'Partner API for Calm Business and Calm Health partners. Provisions and manages Calm subscriptions for partner end users via OAuth 2.0 client credentials. Three operations cover the full subscription lifecycle: authorize the partner service, link a partner user to a Calm subscription, and cancel an existing subscription. Credentials are issued by Calm''s B2B Engineering Team.'
  version: '0'
  contact:
    name: Calm B2B Engineering Team
    url: https://partner.calm.com/docs/api
  license:
    name: Calm Partner Terms
    url: https://www.calm.com/terms
servers:
- url: https://auth.calm.com
  description: Production
- url: https://auth-ga.aws-dev.useast1.calm.com
  description: Development
tags:
- name: Authentication
  description: OAuth 2.0 client credentials for partner services.
paths:
  /v0/authorize:
    post:
      tags:
      - Authentication
      summary: Authorize Partner Service
      description: Exchange a provisioned client_id and client_secret for a short-lived JWT access token. The token is required to authenticate subsequent Partner API calls.
      operationId: authorizePartner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeRequest'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '401':
          description: Invalid client credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
    AuthorizeRequest:
      type: object
      required:
      - client_id
      - client_secret
      - grant_type
      properties:
        client_id:
          type: string
          description: Partner client identifier issued by Calm.
        client_secret:
          type: string
          description: Partner client secret issued by Calm.
        grant_type:
          type: string
          enum:
          - client_credentials
          description: OAuth 2.0 grant type.
    AccessToken:
      type: object
      required:
      - access_token
      - token_type
      - expires_at
      properties:
        access_token:
          type: string
          description: JWT bearer token.
        token_type:
          type: string
          enum:
          - Bearer
        expires_at:
          type: integer
          format: int64
          description: Unix epoch seconds at which the token expires.
        token_id:
          type: string
          description: Opaque identifier for the issued token.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token issued by POST /v0/authorize.