openapi: 3.0.3
info:
  title: Admin API
  description: |
    <a href="/openapi/ui/admin-openapi.yaml" target="_blank" download="admin-openapi.yaml"><button>Download OpenAPI Specification</button></a>

    The **Admin API** serves as the central point for interacting with Witboost.
  version: '0.1.0'
tags:
  - name: Admin
paths:
  /api/auth/access-tokens/jwt:
    post:
      tags:
        - Admin
      summary: Exchange an access token for a short-lived JWT
      description: |
        Exchanges a Witboost access token for a short-lived JWT to authenticate API calls.

        **Rules:**
        - `duration_seconds` cannot exceed the remaining lifetime of the access token. If it does, the request is rejected.
        - If `duration_seconds` is not provided, a default duration is used (configured by `backend.auth.shortLivedTokendurationSeconds`, default: 5 minutes).
        - The `scope` field accepts a space-separated list of scopes (e.g., `scope1 scope2 scope3`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessTokenJwtRequest'
            examples:
              default:
                value:
                  access_token: 'wbat-YY4BMWsHE-tRQ5ZH5HWop_0AjukY4wOPOrx'
                  duration_seconds: 3600
                  scope: 'scope-1 scope-2 scope-3'
      responses:
        200:
          description: JWT successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenJwtResponse'
              examples:
                success:
                  value:
                    jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
        500:
          description: System problem
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  value:
                    error:
                      message: 'An error occurred while creating the JWT'

components:
  schemas:
    AccessTokenJwtRequest:
      type: object
      description: Request to exchange an access token for a short-lived JWT
      required:
        - access_token
      properties:
        access_token:
          type: string
          description: The Witboost access token to exchange
          example: wbat-YY4BMWsHE-tRQ5ZH5HWop_0AjukY4wOPOrx
        duration_seconds:
          type: integer
          minimum: 1
          description: >
            Lifetime of the generated JWT in seconds. If omitted, the backend default is used (configured by `backend.auth.shortLivedTokenduration_seconds`, default: 5 minutes)
          example: 3600
        scope:
          type: string
          description: Space-separated list of scopes for the generated JWT
          example: service:computational-governance

    AccessTokenJwtResponse:
      type: object
      description: Response containing the generated JWT
      required:
        - jwt
      properties:
        jwt:
          type: string
          description: The generated JWT token
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              description: An informative user-friendly message that informs about any occurred error during the hook update
          additionalProperties: true