openapi: 3.0.3
info:
  title: Telonium STIR/SHAKEN Certificate API
  version: "1.0.0"
  description: |
    Programmatic access to the certificate operations available in the
    Telonium STIR/SHAKEN Manager dashboard: list, look up, request, renew,
    deactivate, and revoke STIR/SHAKEN certificates.

    Every API key belongs to exactly one company and one or more scopes.
    All endpoints are scoped to that company automatically -- there is no
    company parameter to pass or spoof.

    API access requires a paid subscription plan. A company on the free
    plan cannot create or use API keys; existing keys stop working
    immediately if the company falls back to free (plan expiry or
    cancellation).
  contact:
    name: Telonium
    url: https://admin.stirshaken.tel/api-keys/docs
  license:
    name: Proprietary
    url: https://sti.telonium.com/terms
servers:
  - url: https://admin.stirshaken.tel/api/v1
    description: Production

security:
  - apiKeyAuth: []

tags:
  - name: certificates
    description: STIR/SHAKEN certificate lifecycle operations

paths:
  /certificates:
    get:
      operationId: listCertificates
      summary: List certificates
      description: Enumerates certificates for the calling company.
      tags: [certificates]
      security:
        - apiKeyAuth: [certificates:list]
      parameters:
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CertificateStatus'
        - name: ocn
          in: query
          required: false
          description: Filter to certificates issued under this OCN.
          schema:
            type: string
            example: ZZZZ
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
      responses:
        '200':
          description: A page of certificates.
          content:
            application/json:
              schema:
                type: object
                required: [data, page, perPage, total]
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CertificateSummary'
                  page:
                    type: integer
                  perPage:
                    type: integer
                  total:
                    type: integer
              examples:
                default:
                  value:
                    data:
                      - certificateSerial: 7f2e1a9c-4b3d-4a1e-9c2f-1a2b3c4d5e6f
                        status: active
                        label: Production Server
                        ocn: ZZZZ
                        issueDate: "2026-06-01T00:00:00.000Z"
                        expirationDate: "2027-06-01T00:00:00.000Z"
                        validityPeriod: 1_year
                        isRenewal: false
                        x5uUrl: https://certs.stirshaken.tel/7f2e1a9c.pem
                        revokedAt: null
                        revocationReason: null
                    page: 1
                    perPage: 25
                    total: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'

    post:
      operationId: requestCertificate
      summary: Request a new certificate
      description: |
        Issues a new certificate for one of the company's OCNs.
        `validityPeriod` is capped by the OCN's subscription plan
        regardless of what's requested. `spcToken` is required unless
        iConectiv credentials are saved in Company Profile, in which case
        it's fetched automatically.
      tags: [certificates]
      security:
        - apiKeyAuth: [certificates:request]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ocn, validityPeriod]
              properties:
                ocn:
                  type: string
                  example: ZZZZ
                validityPeriod:
                  $ref: '#/components/schemas/ValidityPeriod'
                label:
                  type: string
                  nullable: true
                  example: Production Server
                spcToken:
                  type: string
                  nullable: true
                  description: Required unless iConectiv credentials are saved in Company Profile.
      responses:
        '201':
          description: Certificate issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateIssuedResponse'
              examples:
                newKeypair:
                  summary: New keypair generated (no CSR/spcToken reuse)
                  value:
                    data:
                      certificateSerial: 7f2e1a9c-4b3d-4a1e-9c2f-1a2b3c4d5e6f
                      status: active
                      label: Production Server
                      ocn: ZZZZ
                      issueDate: "2026-08-30T00:00:00.000Z"
                      expirationDate: "2027-08-30T00:00:00.000Z"
                      validityPeriod: 1_year
                      isRenewal: false
                      x5uUrl: https://certs.stirshaken.tel/7f2e1a9c.pem
                      revokedAt: null
                      revocationReason: null
                      certificateData: |-
                        -----BEGIN CERTIFICATE-----
                        MIIC...
                        -----END CERTIFICATE-----
                    p12Password: a1b2c3d4e5f6...
                    p12Base64: MIIKXAIBAzCCCh...==
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The given OCN was not found for this company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'

  /certificates/{serial}:
    parameters:
      - $ref: '#/components/parameters/CertificateSerial'
    get:
      operationId: getCertificate
      summary: Get a certificate
      description: |
        Looks up one certificate by `certificateSerial`. Same shape as the
        list response, plus `certificateData` -- the public PEM, the same
        bytes already served at `x5uUrl`.
      tags: [certificates]
      security:
        - apiKeyAuth: [certificates:get]
      responses:
        '200':
          description: The certificate.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: '#/components/schemas/CertificateDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'

  /certificates/{serial}/renew:
    parameters:
      - $ref: '#/components/parameters/CertificateSerial'
    post:
      operationId: renewCertificate
      summary: Renew a certificate
      description: |
        Same body as request (minus `ocn`, inherited from the certificate
        being renewed). The old certificate is marked `renewed`, not
        revoked. When the original certificate still has its signing
        request on file, renewal reuses the existing private key and the
        response omits `p12Password`/`p12Base64` entirely (`usedExistingKey:
        true`) rather than sending them as null -- check for their
        presence, not their value.
      tags: [certificates]
      security:
        - apiKeyAuth: [certificates:renew]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [validityPeriod]
              properties:
                validityPeriod:
                  $ref: '#/components/schemas/ValidityPeriod'
                label:
                  type: string
                  nullable: true
                spcToken:
                  type: string
                  nullable: true
      responses:
        '201':
          description: Certificate renewed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateRenewedResponse'
              examples:
                reusedKey:
                  summary: Existing CSR on file -- key reused, no p12 data
                  value:
                    data:
                      certificateSerial: 9a1b8c7d-6e5f-4a1e-9c2f-1a2b3c4d5e6f
                      status: active
                      label: Production Server
                      ocn: ZZZZ
                      issueDate: "2026-08-30T00:00:00.000Z"
                      expirationDate: "2027-08-30T00:00:00.000Z"
                      validityPeriod: 1_year
                      isRenewal: true
                      x5uUrl: https://certs.stirshaken.tel/9a1b8c7d.pem
                      revokedAt: null
                      revocationReason: null
                      certificateData: |-
                        -----BEGIN CERTIFICATE-----
                        MIIC...
                        -----END CERTIFICATE-----
                    usedExistingKey: true
                newKeypair:
                  summary: No CSR on file -- fresh keypair generated
                  value:
                    data:
                      certificateSerial: 9a1b8c7d-6e5f-4a1e-9c2f-1a2b3c4d5e6f
                      status: active
                      label: Production Server
                      ocn: ZZZZ
                      issueDate: "2026-08-30T00:00:00.000Z"
                      expirationDate: "2027-08-30T00:00:00.000Z"
                      validityPeriod: 1_year
                      isRenewal: true
                      x5uUrl: https://certs.stirshaken.tel/9a1b8c7d.pem
                      revokedAt: null
                      revocationReason: null
                      certificateData: |-
                        -----BEGIN CERTIFICATE-----
                        MIIC...
                        -----END CERTIFICATE-----
                    p12Password: a1b2c3d4e5f6...
                    p12Base64: MIIKXAIBAzCCCh...==
                    usedExistingKey: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'

  /certificates/{serial}/deactivate:
    parameters:
      - $ref: '#/components/parameters/CertificateSerial'
    post:
      operationId: deactivateCertificate
      summary: Deactivate a certificate
      description: |
        Removes the certificate's public URL (x5u) only -- it does **not**
        revoke the certificate. Status is unchanged; the public PEM is
        permanently deleted and will no longer resolve. Irreversible. No
        request body.
      tags: [certificates]
      security:
        - apiKeyAuth: [certificates:deactivate]
      responses:
        '200':
          description: Certificate deactivated.
          content:
            application/json:
              schema:
                type: object
                required: [success, certificateSerial]
                properties:
                  success:
                    type: boolean
                    example: true
                  certificateSerial:
                    type: string
                    format: uuid
              examples:
                default:
                  value:
                    success: true
                    certificateSerial: 7f2e1a9c-4b3d-4a1e-9c2f-1a2b3c4d5e6f
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'

  /certificates/{serial}/revoke:
    parameters:
      - $ref: '#/components/parameters/CertificateSerial'
    post:
      operationId: revokeCertificate
      summary: Revoke a certificate
      description: |
        Two-step: call once with a `reason` to validate the request and
        obtain a short-lived `confirmationToken` (5-minute expiry) instead
        of revoking anything, then call again with that token to actually
        execute the revocation. There's no human to type a confirmation
        phrase for a server-to-server caller, so two deliberate round
        trips stand in for it. The confirmation step doesn't take `reason`
        again -- it's embedded in the token from step 1, so what gets
        confirmed always matches exactly what was validated.
      tags: [certificates]
      security:
        - apiKeyAuth: [certificates:revoke]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/RevokeRequestStep1'
                - $ref: '#/components/schemas/RevokeRequestStep2'
            examples:
              step1:
                summary: "Step 1: validate and request confirmation"
                value:
                  reason: keyCompromise
              step2:
                summary: "Step 2: confirm and execute"
                value:
                  confirmationToken: eyJjZXJ0...signature
      responses:
        '200':
          description: Either a confirmation request (step 1) or the executed revocation (step 2), depending on the request body.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RevokeConfirmationResponse'
                  - $ref: '#/components/schemas/RevokeExecutedResponse'
              examples:
                confirmationRequested:
                  summary: "Step 1 response"
                  value:
                    requiresConfirmation: true
                    certificateSerial: 7f2e1a9c-4b3d-4a1e-9c2f-1a2b3c4d5e6f
                    confirmationToken: eyJjZXJ0...signature
                    expiresAt: "2026-08-29T12:05:00.000Z"
                    message: "Revocation not yet executed. POST again to this same endpoint with this confirmationToken before it expires to actually revoke the certificate."
                executed:
                  summary: "Step 2 response"
                  value:
                    success: true
                    certificateSerial: 7f2e1a9c-4b3d-4a1e-9c2f-1a2b3c4d5e6f
        '400':
          description: |
            Invalid/missing JSON body, missing or invalid `reason`, an
            invalid or expired `confirmationToken`, or the certificate is
            not currently `active` (only an active certificate can be
            revoked).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'

components:
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: stir_live_<prefix>.<secret>
      description: |
        Pass the key shown once at creation on the API Keys page:
        `Authorization: Bearer stir_live_<prefix>.<secret>`.

  parameters:
    CertificateSerial:
      name: serial
      in: path
      required: true
      description: The certificate's `certificateSerial` (a UUID).
      schema:
        type: string
        format: uuid
      example: 7f2e1a9c-4b3d-4a1e-9c2f-1a2b3c4d5e6f

  responses:
    BadRequest:
      description: Invalid input.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid, revoked, or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The API key is missing the required scope, or the company is on the free plan.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Certificate (or OCN) not found for this company.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limited -- 60 requests per minute per key by default.
      headers:
        Retry-After:
          description: Seconds until the rate-limit window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Rate limit exceeded: 60 requests per minute."
    ServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
      example:
        error: "This API key is missing the required scope: certificates:request"

    CertificateStatus:
      type: string
      enum: [active, expired, revoked, pending, renewed]

    ValidityPeriod:
      type: string
      enum: [24_hours, 1_week, 1_month, 3_months, 6_months, 1_year, max]
      description: Actual validity granted is capped by the OCN's subscription plan.

    RevocationReason:
      type: string
      enum: [unspecified, keyCompromise, affiliationChanged, superseded, cessationOfOperation, privilegeWithdrawn]
      description: X.509 CRLReason values applicable to a service provider revoking its own end-entity certificate.

    CertificateSummary:
      type: object
      required:
        - certificateSerial
        - status
        - label
        - ocn
        - issueDate
        - expirationDate
        - validityPeriod
        - isRenewal
        - x5uUrl
        - revokedAt
        - revocationReason
      properties:
        certificateSerial:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/CertificateStatus'
        label:
          type: string
          nullable: true
        ocn:
          type: string
          nullable: true
        issueDate:
          type: string
          format: date-time
        expirationDate:
          type: string
          format: date-time
        validityPeriod:
          type: string
          nullable: true
          enum: [24_hours, 1_week, 1_month, 3_months, 6_months, 1_year, max, null]
          description: Same values as ValidityPeriod; capped by the OCN's subscription plan.
        isRenewal:
          type: boolean
        x5uUrl:
          type: string
          format: uri
          nullable: true
          description: Null after the certificate has been deactivated.
        revokedAt:
          type: string
          format: date-time
          nullable: true
        revocationReason:
          type: string
          nullable: true
          enum: [unspecified, keyCompromise, affiliationChanged, superseded, cessationOfOperation, privilegeWithdrawn, null]
          description: Same values as RevocationReason.

    CertificateDetail:
      allOf:
        - $ref: '#/components/schemas/CertificateSummary'
        - type: object
          required: [certificateData]
          properties:
            certificateData:
              type: string
              nullable: true
              description: Public leaf+intermediate PEM bundle -- the same bytes already served at `x5uUrl`.

    CertificateIssuedResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/CertificateDetail'
        p12Password:
          type: string
          description: |
            Present only when a new private key was generated. Shown
            **exactly once**, in this response -- never stored, never
            retrievable again.
        p12Base64:
          type: string
          description: Base64-encoded PKCS#12 bundle, present only alongside `p12Password`.

    CertificateRenewedResponse:
      type: object
      required: [data, usedExistingKey]
      properties:
        data:
          $ref: '#/components/schemas/CertificateDetail'
        p12Password:
          type: string
          description: Present only when `usedExistingKey` is false.
        p12Base64:
          type: string
          description: Present only when `usedExistingKey` is false.
        usedExistingKey:
          type: boolean
          description: True when the renewal reused the original CSR's key (no p12 data returned); false when a fresh keypair was generated.

    RevokeRequestStep1:
      type: object
      required: [reason]
      properties:
        reason:
          $ref: '#/components/schemas/RevocationReason'

    RevokeRequestStep2:
      type: object
      required: [confirmationToken]
      properties:
        confirmationToken:
          type: string

    RevokeConfirmationResponse:
      type: object
      required: [requiresConfirmation, certificateSerial, confirmationToken, expiresAt, message]
      properties:
        requiresConfirmation:
          type: boolean
          example: true
        certificateSerial:
          type: string
          format: uuid
        confirmationToken:
          type: string
        expiresAt:
          type: string
          format: date-time
        message:
          type: string

    RevokeExecutedResponse:
      type: object
      required: [success, certificateSerial]
      properties:
        success:
          type: boolean
          example: true
        certificateSerial:
          type: string
          format: uuid
