openapi: 3.1.0
info:
  title: Nabla Core Authentication API
  description: 'Nabla provides ambient AI for clinicians. The Core API supports

    transcription (synchronous, asynchronous, and WebSocket) of medical

    encounters. The Server API issues OAuth 2.0 access tokens via JWT

    client credentials, and the User API exchanges per-user JWT tokens

    so that client applications can call the Core API on behalf of a

    Copilot user.

    '
  version: '1.0'
servers:
- url: https://api.nabla.com
  description: Nabla production API
security:
- bearerAuth: []
tags:
- name: Authentication
  description: OAuth and JWT token endpoints.
paths:
  /oauth/token:
    post:
      tags:
      - Authentication
      summary: Issue a server access token (OAuth 2.0 client credentials)
      description: 'Exchange a JWT client assertion (RS256) for an OAuth 2.0 access

        token used to authenticate Server API requests. Tokens typically

        expire in one hour.

        '
      operationId: oauthToken
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - grant_type
              - client_assertion_type
              - client_assertion
              properties:
                grant_type:
                  type: string
                  enum:
                  - client_credentials
                client_assertion_type:
                  type: string
                  enum:
                  - urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                client_assertion:
                  type: string
                scope:
                  type: string
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                  expires_in:
                    type: integer
        '401':
          description: Invalid client assertion.
  /jwt/authenticate/{user_id}:
    post:
      tags:
      - Authentication
      summary: Issue per-user access and refresh tokens
      description: 'Server-to-server endpoint that mints access and refresh tokens

        scoped to a single Copilot user, allowing a client application

        to act on behalf of that user when calling the Core API.

        '
      operationId: jwtAuthenticate
      parameters:
      - in: path
        name: user_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User tokens issued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  refresh_token:
                    type: string
                  expires_in:
                    type: integer
  /jwt/refresh:
    post:
      tags:
      - Authentication
      summary: Refresh a user access token
      operationId: jwtRefresh
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - refresh_token
              properties:
                refresh_token:
                  type: string
      responses:
        '200':
          description: New access token issued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token (Server API) or JWT access token (User API).