openapi: 3.0.3
info:
  title: Calm Partner Authentication Subscriptions 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: Subscriptions
  description: Provision and revoke Calm subscriptions linked to partner users.
paths:
  /v0/b2b/users/link:
    post:
      tags:
      - Subscriptions
      summary: Link Partner User to Calm Subscription
      description: Provision a Calm subscription linked to a unique partner user. Returns a one-time-use link that redirects the end user into the Calm signup/login flow.
      operationId: linkPartnerUser
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkUserRequest'
      responses:
        '200':
          description: Subscription provisioned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkUserResponse'
        '401':
          description: Missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Partner user already linked to an active subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/b2b/users/{partner_user_id}:
    delete:
      tags:
      - Subscriptions
      summary: Cancel Partner User Subscription
      description: Cancel the Calm subscription associated with a partner user so it will not auto-renew. Returns the cancellation status and expiry timestamp.
      operationId: cancelPartnerUserSubscription
      security:
      - bearerAuth: []
      parameters:
      - name: partner_user_id
        in: path
        required: true
        description: Unique identifier for the user within the partner's system.
        schema:
          type: string
      responses:
        '200':
          description: Subscription canceled or not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelSubscriptionResponse'
        '401':
          description: Missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CancelSubscriptionResponse:
      type: object
      required:
      - partner_user_id
      - status
      properties:
        partner_user_id:
          type: string
        calm_user_id:
          type: string
        expires:
          type: string
          format: date-time
          description: Timestamp at which the subscription expires.
        status:
          type: string
          enum:
          - canceled
          - not_found
    Error:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
    LinkUserResponse:
      type: object
      required:
      - partner_user_id
      - link_url
      properties:
        partner_user_id:
          type: string
        calm_user_id:
          type: string
          description: Calm-side user identifier.
        link_url:
          type: string
          format: uri
          description: Redirect URL that completes Calm signup/login for the user.
        status:
          type: string
          enum:
          - active
          - pending
    LinkUserRequest:
      type: object
      required:
      - partner_user_id
      properties:
        partner_user_id:
          type: string
          description: Unique identifier for the user within the partner's system.
        email:
          type: string
          format: email
          description: Optional end-user email used for the Calm account.
        first_name:
          type: string
        last_name:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token issued by POST /v0/authorize.