openapi: 3.0.1
info:
  title: Zus Health Auth API
  description: FHIR R4 (v4.0.1) REST API for the Zus Health shared health-data platform. Provides access to Patient resources, the Zus Aggregated Profile (ZAP) via Patient History jobs, general FHIR resources, document ingestion and retrieval through DocumentReference and Binary, and OAuth2 token issuance. All requests are authenticated with an OAuth2 Bearer access token. Endpoints and behavior are derived from the public Zus documentation at https://docs.zushealth.com; production hostnames use api.zusapi.com and the sandbox uses api.sandbox.zusapi.com / auth.sandbox.zusapi.com.
  termsOfService: https://zushealth.com
  contact:
    name: Zus Health
    url: https://docs.zushealth.com
  version: '1.0'
servers:
- url: https://api.zusapi.com
  description: Production
- url: https://api.sandbox.zusapi.com
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Auth
  description: OAuth2 token issuance and exchange.
paths:
  /oauth/token:
    servers:
    - url: https://auth.zusapi.com
      description: Production auth
    - url: https://auth.sandbox.zusapi.com
      description: Sandbox auth
    post:
      operationId: createToken
      tags:
      - Auth
      summary: Issue or exchange an OAuth2 access token.
      description: Exchange credentials for a Zus access token. Supports the authorization_code (with PKCE) grant and the RFC 8693 token-exchange grant (grant_type urn:ietf:params:oauth:grant-type:token-exchange) for exchanging a third-party IdP ID token. Access tokens are valid for one hour (expires_in 3600). The token endpoint is rate limited to 200 requests per hour per App Client.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid credentials.
components:
  schemas:
    TokenRequest:
      type: object
      required:
      - grant_type
      properties:
        grant_type:
          type: string
          description: authorization_code or urn:ietf:params:oauth:grant-type:token-exchange.
        client_id:
          type: string
        code:
          type: string
        code_verifier:
          type: string
        redirect_uri:
          type: string
        subject_token:
          type: string
          description: Third-party IdP ID token (token-exchange grant).
        subject_token_type:
          type: string
        scope:
          type: string
          example: openid profile email
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          example: 3600
        scope:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OAuth2 Bearer access token obtained from the Zus token endpoint (auth.zusapi.com/oauth/token). Sent as Authorization: Bearer <ACCESS_TOKEN>.'