platform-setup-openapi.yaml

openapi: 3.1.0
info:
  title: Platform Setup API
  version: 1.0.0
  description: |
    Anonymous first-run setup API exposed only while the durable bootstrap gate is open.
    The API creates a signed local license request through persistent KMS storage,
    installs the issued deployment license, and enables the platform tenant with
    a natural-person operator login on the platform-integrated authorization server.
servers:
  - url: https://api.example.com/api/platform/setup/v1
    description: Production
  - url: http://localhost:8080/api/platform/setup/v1
    description: Local development
tags:
  - name: Setup
security: []
paths:
  /status:
    get:
      tags: [Setup]
      operationId: getSetupStatus
      summary: Get first-run setup readiness
      responses:
        '200':
          description: Setup gate is open.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupStatus'
        '404':
          description: Setup gate is closed.
  /license-request:
    get:
      tags: [Setup]
      operationId: getSetupLicenseRequestStatus
      summary: Get configured license request defaults
      responses:
        '200':
          description: KMS license request defaults.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseRequestStatus'
        '404':
          description: Setup gate is closed.
  /license-request/generate:
    post:
      tags: [Setup]
      operationId: generateSetupLicenseRequest
      summary: Generate a signed local license request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateLicenseRequestRequest'
      responses:
        '200':
          description: Signed license request to deliver manually to the license issuer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseRequestResponse'
        '404':
          description: Setup gate is closed.
  /license/verify:
    post:
      tags: [Setup]
      operationId: verifySetupLicense
      summary: Verify a license token without installing it
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseTokenRequest'
      responses:
        '200':
          description: License verification result.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Setup gate is closed.
  /license/install:
    post:
      tags: [Setup]
      operationId: installSetupLicense
      summary: Install the deployment license token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseTokenRequest'
      responses:
        '200':
          description: Active license snapshot.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Setup gate is closed.
  /bootstrap:
    post:
      tags: [Setup]
      operationId: bootstrapPlatform
      summary: Enable the platform tenant and operator login
      description: |
        Creates or reconciles the internal platform tenant, seeds the platform-integrated
        authorization server, creates the initial natural-person operator identity, sets
        the operator credential, and closes the first-run setup gate. Production tenants
        are created afterwards through the authenticated platform admin API.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BootstrapTenantRequest'
      responses:
        '201':
          description: Platform bootstrap result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BootstrapTenantResponse'
        '404':
          description: Setup gate is closed.
components:
  schemas:
    SetupStatus:
      type: object
      required: [gateOpen, firstTenantConfigMissingKeys, emailConfigured, licenseConfigured]
      properties:
        gateOpen:
          type: boolean
        firstTenantConfigMissingKeys:
          type: array
          items:
            type: string
        emailConfigured:
          type: boolean
        licenseConfigured:
          type: boolean
        licenseRequestKmsConfigured:
          type: boolean
        licenseRequestDefaultAlias:
          type: string
    LicenseDeliveryMethod:
      type: string
      enum: [MANUAL]
    LicenseRequestStatus:
      type: object
      required: [kmsConfigured, defaultAlias, defaultAlgorithm, defaultUse, licenseDeliveryMethod]
      properties:
        kmsConfigured:
          type: boolean
        kmsBaseUrl:
          anyOf:
            - type: string
            - type: 'null'
        defaultProviderId:
          anyOf:
            - type: string
            - type: 'null'
        defaultAlias:
          type: string
        defaultAlgorithm:
          type: string
          example: ECDSA_SHA256
        defaultUse:
          type: string
          example: sig
        licenseDeliveryMethod:
          $ref: '#/components/schemas/LicenseDeliveryMethod'
    LicenseRequestDeployment:
      type: object
      required: [installationBaseDomain, tenantName, tenantSlug, ownerEmail, ownerDisplayName]
      properties:
        installationBaseDomain:
          type: string
          example: edk.example.com
        tenantName:
          type: string
        tenantSlug:
          type: string
        ownerEmail:
          type: string
          format: email
        ownerDisplayName:
          type: string
        organizationName:
          anyOf:
            - type: string
            - type: 'null'
        organizationUnit:
          anyOf:
            - type: string
            - type: 'null'
        locality:
          anyOf:
            - type: string
            - type: 'null'
        state:
          anyOf:
            - type: string
            - type: 'null'
        country:
          anyOf:
            - type: string
              minLength: 2
              maxLength: 2
            - type: 'null'
        licenseDeliveryMethod:
          $ref: '#/components/schemas/LicenseDeliveryMethod'
          default: MANUAL
    GenerateLicenseRequestRequest:
      type: object
      required: [deployment]
      properties:
        alias:
          anyOf:
            - type: string
            - type: 'null'
        providerId:
          anyOf:
            - type: string
            - type: 'null'
        algorithm:
          anyOf:
            - type: string
            - type: 'null'
          default: ECDSA_SHA256
        use:
          anyOf:
            - type: string
            - type: 'null'
          default: sig
        deployment:
          $ref: '#/components/schemas/LicenseRequestDeployment'
        serialNumber:
          anyOf:
            - type: integer
            - type: 'null'
          default: 1
    LocalInstanceCertificate:
      type: object
      required: [derBase64, commonName, serialNumber]
      properties:
        derBase64:
          type: string
          contentEncoding: base64
        commonName:
          type: string
        organizationName:
          anyOf:
            - type: string
            - type: 'null'
        organizationUnit:
          anyOf:
            - type: string
            - type: 'null'
        locality:
          anyOf:
            - type: string
            - type: 'null'
        state:
          anyOf:
            - type: string
            - type: 'null'
        country:
          anyOf:
            - type: string
            - type: 'null'
        email:
          anyOf:
            - type: string
            - type: 'null'
        serialNumber:
          type: integer
    LocalInstancePublicKey:
      type: object
      required: [alias, providerId, publicJwk]
      properties:
        alias:
          type: string
        providerId:
          type: string
        kid:
          anyOf:
            - type: string
            - type: 'null'
        publicJwk:
          type: object
          additionalProperties: true
    LicenseRequestTenant:
      type: object
      required: [name, slug]
      properties:
        name:
          type: string
        slug:
          type: string
    LicenseRequestOwner:
      type: object
      required: [email, displayName]
      properties:
        email:
          type: string
          format: email
        displayName:
          type: string
    LicenseRequestPayload:
      type: object
      required: [version, requestId, generatedAt, installationBaseDomain, platformIssuer, tenant, owner, licenseDeliveryMethod, localCertificate, localPublicKey]
      properties:
        version:
          type: string
        requestId:
          type: string
        generatedAt:
          type: string
          format: date-time
        installationBaseDomain:
          type: string
        platformIssuer:
          type: string
          format: uri
        tenant:
          $ref: '#/components/schemas/LicenseRequestTenant'
        owner:
          $ref: '#/components/schemas/LicenseRequestOwner'
        organizationName:
          anyOf:
            - type: string
            - type: 'null'
        organizationUnit:
          anyOf:
            - type: string
            - type: 'null'
        licenseDeliveryMethod:
          $ref: '#/components/schemas/LicenseDeliveryMethod'
        localCertificate:
          $ref: '#/components/schemas/LocalInstanceCertificate'
        localPublicKey:
          $ref: '#/components/schemas/LocalInstancePublicKey'
    LicenseRequestSignature:
      type: object
      required: [algorithm, signatureBase64]
      properties:
        algorithm:
          type: string
        keyId:
          anyOf:
            - type: string
            - type: 'null'
        signatureBase64:
          type: string
          contentEncoding: base64
    LicenseRequestResponse:
      type: object
      required: [request, requestJson, signature]
      properties:
        request:
          $ref: '#/components/schemas/LicenseRequestPayload'
        requestJson:
          type: string
        signature:
          $ref: '#/components/schemas/LicenseRequestSignature'
    LicenseTokenRequest:
      type: object
      required: [licenseToken]
      properties:
        licenseToken:
          type: string
    BootstrapTenantRequest:
      type: object
      required: [operatorEmail, operatorDisplayName, operatorPassword]
      properties:
        operatorEmail:
          type: string
          format: email
        operatorDisplayName:
          type: string
        operatorPassword:
          type: string
          minLength: 12
          writeOnly: true
    BootstrapTenantResponse:
      type: object
      required: [tenantId, status, operatorEmail, canCreateProductionTenants]
      properties:
        tenantId:
          type: string
        status:
          type: string
          enum: [ACTIVE, SUSPENDED, PENDING_VERIFICATION]
        hostedAsIssuerUrl:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
        operatorEmail:
          type: string
          format: email
        canCreateProductionTenants:
          type: boolean