openapi: 3.0.3
info:
  title: Aurea License API
  version: "1.0"
  description: >
    Public API used by Aurea on-premise environments to download signed license
    files for licensed organizations.
servers:
  - url: https://license.aurea.software
    description: Aurea License Portal
paths:
  /api/v1/organizations/{organizationId}/license:
    get:
      summary: Download organization license file
      description: >
        Downloads the current signed license file for a licensed Aurea
        organization. The request must use the license download token assigned to
        the same organization.
      operationId: downloadOrganizationLicense
      tags:
        - License
      parameters:
        - name: organizationId
          in: path
          required: true
          description: Aurea organization identifier.
          schema:
            type: string
          example: org_01k2n7pmv9y4z6c5r8f2wq3hda
      security:
        - licenseDownloadToken: []
      responses:
        "200":
          description: Signed license file.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignedLicenseFile"
              examples:
                standardProduction:
                  summary: Standard production organization license
                  value:
                    payload:
                      schemaVersion: 1
                      licenseId: lic_01k2n8a7c6m5t4x3z2p1q0w9er
                      licenseType: subscription
                      plan: standard
                      account:
                        accountId: acct_01k2n70av9q2e8j4s6r1m5t3yw
                        name: Tecna Sp. z o.o.
                      organization:
                        organizationId: org_01k2n7pmv9y4z6c5r8f2wq3hda
                        name: Tecna
                        environmentType: production
                      validity:
                        issuedAt: "2026-06-15T12:00:00Z"
                        validFrom: "2026-06-15T12:00:00Z"
                        validUntil: "2026-07-17T12:00:00Z"
                        graceUntil: "2026-07-31T12:00:00Z"
                      entitlements:
                        - code: users.active
                          type: limit
                          metric: active_users
                          value: 50
                        - code: aurea.core
                          type: feature
                          value: true
                    signature:
                      algorithm: Ed25519
                      canonicalization: jcs-rfc8785
                      keyId: aurea-license-signing-2026-01
                      value: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
        "401":
          description: Missing, malformed or invalid license download token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                unauthorized:
                  value:
                    error: unauthorized
                    message: Missing or invalid license download token.
        "404":
          description: Licensed organization was not found or is not accessible with the provided token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                notFound:
                  value:
                    error: not_found
                    message: Licensed organization was not found.
        "409":
          description: License is not available for this organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                licenseUnavailable:
                  value:
                    error: license_unavailable
                    message: License is not available for this organization.
components:
  securitySchemes:
    licenseDownloadToken:
      type: http
      scheme: bearer
      bearerFormat: license-download-token
      description: License download token assigned to one licensed organization. Tokens use the `ldt_` prefix.
  schemas:
    SignedLicenseFile:
      type: object
      required:
        - payload
        - signature
      properties:
        payload:
          $ref: "#/components/schemas/LicensePayload"
        signature:
          $ref: "#/components/schemas/LicenseSignature"
      additionalProperties: false
    LicensePayload:
      type: object
      required:
        - schemaVersion
        - licenseId
        - licenseType
        - plan
        - account
        - organization
        - validity
        - entitlements
      properties:
        schemaVersion:
          type: integer
          example: 1
        licenseId:
          type: string
          example: lic_01k2n8a7c6m5t4x3z2p1q0w9er
        licenseType:
          type: string
          enum:
            - subscription
          example: subscription
        plan:
          type: string
          enum:
            - standard
          example: standard
        account:
          $ref: "#/components/schemas/LicenseAccount"
        organization:
          $ref: "#/components/schemas/LicenseOrganization"
        validity:
          $ref: "#/components/schemas/LicenseValidity"
        entitlements:
          type: array
          items:
            $ref: "#/components/schemas/LicenseEntitlement"
      additionalProperties: false
    LicenseAccount:
      type: object
      required:
        - accountId
        - name
      properties:
        accountId:
          type: string
          example: acct_01k2n70av9q2e8j4s6r1m5t3yw
        name:
          type: string
          example: Tecna Sp. z o.o.
      additionalProperties: false
    LicenseOrganization:
      type: object
      required:
        - organizationId
        - name
        - environmentType
      properties:
        organizationId:
          type: string
          example: org_01k2n7pmv9y4z6c5r8f2wq3hda
        name:
          type: string
          example: Tecna
        environmentType:
          type: string
          enum:
            - production
            - staging
            - test
            - development
          example: production
      additionalProperties: false
    LicenseValidity:
      type: object
      required:
        - issuedAt
        - validFrom
        - validUntil
        - graceUntil
      properties:
        issuedAt:
          type: string
          format: date-time
          example: "2026-06-15T12:00:00Z"
        validFrom:
          type: string
          format: date-time
          example: "2026-06-15T12:00:00Z"
        validUntil:
          type: string
          format: date-time
          example: "2026-07-17T12:00:00Z"
        graceUntil:
          type: string
          format: date-time
          example: "2026-07-31T12:00:00Z"
      additionalProperties: false
    LicenseEntitlement:
      type: object
      required:
        - code
        - type
        - value
      properties:
        code:
          type: string
          example: users.active
        type:
          type: string
          enum:
            - limit
            - feature
          example: limit
        metric:
          type: string
          example: active_users
        value:
          oneOf:
            - type: integer
            - type: boolean
          example: 50
      additionalProperties: false
    LicenseSignature:
      type: object
      required:
        - algorithm
        - canonicalization
        - keyId
        - value
      properties:
        algorithm:
          type: string
          enum:
            - Ed25519
          example: Ed25519
        canonicalization:
          type: string
          enum:
            - jcs-rfc8785
          example: jcs-rfc8785
        keyId:
          type: string
          example: aurea-license-signing-2026-01
        value:
          type: string
          description: Base64url-encoded Ed25519 signature over the canonical JSON representation of the payload.
          example: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          example: unauthorized
        message:
          type: string
          example: Missing or invalid license download token.
      additionalProperties: true
