openapi: 3.0.3
info:
  title: TranscriMed Auth API
  description: |
    OAuth2 authentication API for TranscriMed platform integration.
    
    This API implements the OAuth2 authorization code flow for secure partner integrations.
    Partners can authenticate users and obtain access tokens to interact with TranscriMed's
    medical record processing services.
    
    ## Authentication Flow
    
    1. **Authorization Request**: Redirect users to `/oauth/authorize` 
    2. **User Consent**: Users grant permissions via consent screen
    3. **Authorization Code**: System redirects back with authorization code
    4. **Token Exchange**: Exchange code for access token via `/oauth/token`
    5. **API Access**: Use access token to access protected endpoints
    
    ## Security
    
    - All endpoints require HTTPS in production
    - Access tokens are signed with HMAC-SHA256
    - Tokens include scope-based authorization
    - Refresh tokens available for long-term access
    
  version: 1.0.0
  contact:
    name: TranscriMed API Support
    url: https://developers.transcrimed.com.br/support
    email: developers@transcrimed.com.br
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://transcrimed.com.br/terms

servers:
  - url: https://api.transcrimed.com.br
    description: Production server (use test credentials for test mode)
  - url: http://localhost:3003
    description: Development server

paths:
  /api/oauth/authorize:
    get:
      summary: OAuth2 Authorization Endpoint
      description: |
        Initiates the OAuth2 authorization flow. Redirects users to the TranscriMed
        consent screen where they can grant permissions to your application.
        
        This endpoint handles the first step of the OAuth2 flow where users are
        redirected to grant permissions to your application.
      operationId: authorizeOAuth2
      tags:
        - OAuth2 Authentication
      parameters:
        - name: response_type
          in: query
          required: true
          description: Must be "code" for authorization code flow
          schema:
            type: string
            enum: [code]
          example: code
        - name: client_id
          in: query
          required: true
          description: Your registered OAuth2 client ID
          schema:
            type: string
          example: your_client_id_here
        - name: redirect_uri
          in: query
          required: true
          description: URL to redirect after authorization (must be registered)
          schema:
            type: string
            format: uri
          example: https://yourapp.com/callback
        - name: scope
          in: query
          required: true
          description: Space-separated list of requested permissions
          schema:
            type: string
          example: "medical_records:read medical_records:write jobs:read"
        - name: state
          in: query
          required: false
          description: Random string to prevent CSRF attacks
          schema:
            type: string
          example: random_state_string_xyz123
      responses:
        '302':
          description: Redirects to consent screen or back to redirect_uri
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: Redirect URL (consent screen or callback with code)
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
              examples:
                invalid_client:
                  summary: Invalid client ID
                  value:
                    error: invalid_client
                    error_description: Client ID not found or invalid
                invalid_redirect_uri:
                  summary: Invalid redirect URI
                  value:
                    error: invalid_redirect_uri
                    error_description: Redirect URI not registered for this client
                invalid_scope:
                  summary: Invalid scope
                  value:
                    error: invalid_scope
                    error_description: Requested scope is invalid or not allowed
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
              example:
                error: server_error
                error_description: Internal server error during authorization

  /api/oauth/token:
    post:
      summary: OAuth2 Token Endpoint
      description: |
        Exchanges an authorization code for an access token, or refreshes an existing token.
        
        This endpoint supports two grant types:
        - `authorization_code`: Exchange authorization code for access token
        - `refresh_token`: Refresh an expired access token
      operationId: tokenOAuth2
      tags:
        - OAuth2 Authentication
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: '#/components/schemas/AuthorizationCodeRequest'
                - $ref: '#/components/schemas/RefreshTokenRequest'
            examples:
              authorization_code:
                summary: Exchange authorization code
                value:
                  grant_type: authorization_code
                  code: auth_code_received_from_callback
                  redirect_uri: https://yourapp.com/callback
                  client_id: your_client_id_here
                  client_secret: your_client_secret_here
              refresh_token:
                summary: Refresh access token
                value:
                  grant_type: refresh_token
                  refresh_token: your_refresh_token_here
                  client_id: your_client_id_here
                  client_secret: your_client_secret_here
      responses:
        '200':
          description: Successful token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              examples:
                access_token:
                  summary: Successful token exchange
                  value:
                    access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                    token_type: Bearer
                    expires_in: 3600
                    refresh_token: refresh_token_string_here
                    scope: "medical_records:read medical_records:write jobs:read"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
              examples:
                invalid_grant:
                  summary: Invalid authorization code
                  value:
                    error: invalid_grant
                    error_description: Authorization code is invalid or expired
                invalid_client:
                  summary: Invalid client credentials
                  value:
                    error: invalid_client
                    error_description: Client authentication failed
                unsupported_grant_type:
                  summary: Unsupported grant type
                  value:
                    error: unsupported_grant_type
                    error_description: Grant type not supported
        '401':
          description: Unauthorized - Invalid client credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
              example:
                error: invalid_client
                error_description: Client authentication failed
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
              example:
                error: server_error
                error_description: Internal server error during token exchange

  

components:
  schemas:
    AuthorizationCodeRequest:
      type: object
      required:
        - grant_type
        - code
        - redirect_uri
        - client_id
        - client_secret
      properties:
        grant_type:
          type: string
          enum: [authorization_code]
          description: Must be "authorization_code"
        code:
          type: string
          description: Authorization code received from /oauth/authorize
        redirect_uri:
          type: string
          format: uri
          description: Same redirect URI used in authorization request
        client_id:
          type: string
          description: Your registered OAuth2 client ID
        client_secret:
          type: string
          description: Your OAuth2 client secret
      example:
        grant_type: authorization_code
        code: auth_code_received_from_callback
        redirect_uri: https://yourapp.com/callback
        client_id: your_client_id_here
        client_secret: your_client_secret_here

    RefreshTokenRequest:
      type: object
      required:
        - grant_type
        - refresh_token
        - client_id
        - client_secret
      properties:
        grant_type:
          type: string
          enum: [refresh_token]
          description: Must be "refresh_token"
        refresh_token:
          type: string
          description: Valid refresh token
        client_id:
          type: string
          description: Your registered OAuth2 client ID
        client_secret:
          type: string
          description: Your OAuth2 client secret
        scope:
          type: string
          description: Optional - requested scope (must be subset of original)
      example:
        grant_type: refresh_token
        refresh_token: your_refresh_token_here
        client_id: your_client_id_here
        client_secret: your_client_secret_here

    

    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: JWT access token for API requests
        token_type:
          type: string
          enum: [Bearer]
          description: Always "Bearer"
        expires_in:
          type: integer
          description: Access token lifetime in seconds
        refresh_token:
          type: string
          description: Refresh token for obtaining new access tokens
        scope:
          type: string
          description: Space-separated list of granted scopes
      required:
        - access_token
        - token_type
        - expires_in
      example:
        access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        token_type: Bearer
        expires_in: 3600
        refresh_token: refresh_token_string_here
        scope: "medical_records:read medical_records:write jobs:read"

    OAuth2Error:
      type: object
      properties:
        error:
          type: string
          enum: 
            - invalid_request
            - invalid_client
            - invalid_grant
            - unauthorized_client
            - unsupported_grant_type
            - invalid_scope
            - server_error
            - temporarily_unavailable
            - invalid_redirect_uri
          description: OAuth2 error code
        error_description:
          type: string
          description: Human-readable error description
        error_uri:
          type: string
          format: uri
          description: Optional URI with more error information
      required:
        - error
      example:
        error: invalid_client
        error_description: Client authentication failed

  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /api/oauth/authorize
          tokenUrl: /api/oauth/token
          refreshUrl: /api/oauth/token
          scopes:
            medical_records:read: Read medical records
            medical_records:write: Create and update medical records
            medical_records:delete: Delete medical records
            jobs:read: Read job status and results
            jobs:write: Create, cancel and manage jobs
            worklists:write: Send worklist items from RIS/PACS systems
            worklists:manage: Update worklist item status
            worklists:read: Read worklist items (internal use)

tags:
  - name: OAuth2 Authentication
    description: |
      OAuth2 endpoints for authentication and authorization.
      
      Use these endpoints to implement the OAuth2 authorization code flow
      for secure access to TranscriMed APIs.

externalDocs:
  description: OAuth2 RFC 6749 Specification
  url: https://tools.ietf.org/html/rfc6749