Spotnana Partner Public Keys API

openapi: 3.1.0
info:
  title: Air Partner Public Keys API
  version: v2
  description: APIs to perform search, checkout and book an air pnr
servers:
- url: https://api-ext-sboxmeta.partners.spotnana.com
  description: Sandbox URL
security:
- Bearer: []
tags:
- name: Partner Public Keys
  description: APIs to manage partner public keys for token exchange authentication.
paths:
  /v2/companies/{companyId}/partner-public-keys:
    parameters:
    - name: companyId
      in: path
      description: Organization identifier.
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    post:
      tags:
      - Partner Public Keys
      summary: Add partner public key
      description: 'Adds one or more public keys for a partner organization to use for token exchange authentication. Accessible to TMC, company, and global admins.

        '
      operationId: addPartnerPublicKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddPartnerPublicKeyRequest'
      responses:
        '201':
          description: Keys created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddPartnerPublicKeyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      tags:
      - Partner Public Keys
      summary: List partner public keys
      description: 'Lists partner public keys for a TMC. Accessible to TMC, company, and global admins.

        '
      operationId: listPartnerPublicKeys
      parameters:
      - name: status
        in: query
        description: Filter keys by status. Defaults to ACTIVE.
        required: false
        schema:
          type: string
          enum:
          - ACTIVE
          - REVOKED
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPartnerPublicKeysResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/companies/{companyId}/partner-public-keys/{kid}:
    parameters:
    - name: companyId
      in: path
      description: Organization identifier.
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    - name: kid
      in: path
      description: Key ID (kid field from the JWK).
      required: true
      schema:
        type: string
      example: my-key-1
    delete:
      tags:
      - Partner Public Keys
      summary: Revoke partner public key
      description: 'Revokes a partner public key identified by kid. Accessible to TMC, company, and global admins.

        '
      operationId: revokePartnerPublicKey
      responses:
        '204':
          description: Key revoked successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    AddPartnerPublicKeyRequest:
      type: object
      title: AddPartnerPublicKeyRequest
      required:
      - keyType
      description: 'Request to add a partner public key for token exchange authentication. Set keyType to JWKS and populate the jwks field with the RSA public key in standard JWKS format (RFC 7517).

        '
      properties:
        keyType:
          $ref: '#/components/schemas/PartnerPublicKeyType'
        jwks:
          $ref: '#/components/schemas/PartnerJwks'
          description: JWKS containing the RSA public key. Required when keyType is JWKS.
    ErrorParameter:
      type: object
      title: ErrorParameter
      description: Error parameter
      properties:
        name:
          type: string
          description: Parameter name
        value:
          type: string
          description: Parameter value
    AddPartnerPublicKeyResponse:
      type: object
      title: AddPartnerPublicKeyResponse
      description: Response containing the partner public keys that were added.
      properties:
        keys:
          type: array
          description: List of added partner public keys.
          items:
            $ref: '#/components/schemas/PartnerPublicKeyInfo'
    PartnerJwks:
      type: object
      description: A JSON Web Key Set (JWKS) per RFC 7517.
      required:
      - keys
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/JwkPublicKey'
          description: List of public keys. Exactly one key must be provided per request.
    PartnerPublicKeyType:
      type: string
      description: The type of public key being registered.
      enum:
      - JWKS
    JwkPublicKey:
      type: object
      description: RSA public key in JWK format (RFC 7517). Only RSA signature keys are supported.
      required:
      - kty
      - use
      - alg
      - kid
      - n
      - e
      properties:
        kty:
          type: string
          enum:
          - RSA
          description: Key type. Only RSA is supported.
        use:
          type: string
          enum:
          - sig
          description: Key use. Must be sig (signature).
        alg:
          type: string
          enum:
          - RS256
          description: Signing algorithm. Must be RS256.
        kid:
          type: string
          description: Key ID — used to match the JWT header kid during token exchange.
        n:
          type: string
          description: RSA modulus (base64url-encoded).
        e:
          type: string
          description: RSA public exponent (base64url-encoded).
    PartnerPublicKeyInfo:
      type: object
      title: PartnerPublicKeyInfo
      description: A partner public key registered for token exchange authentication.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the key.
        orgId:
          type: string
          format: uuid
          description: Organization this key is scoped to.
        kid:
          type: string
          description: Key ID extracted from the JWK.
        status:
          type: string
          description: Key status.
          enum:
          - ACTIVE
          - REVOKED
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the key was created.
        thumbprint:
          type: string
          readOnly: true
          description: 'RFC 7638 JWK thumbprint (base64url SHA-256 of canonical key material). Use this to verify the correct key was registered.

            '
    ErrorResponse:
      type: object
      properties:
        debugIdentifier:
          type: string
          description: Link to debug the error internally.
        errorMessages:
          type: array
          items:
            type: object
            properties:
              errorCode:
                type: string
                description: Error code to identify the specific errors.
              message:
                type: string
                description: Message containing details of error.
              errorParameters:
                type: array
                description: Error message parameters.
                items:
                  $ref: '#/components/schemas/ErrorParameter'
              errorDetail:
                type: string
                description: More details about the error.
    ListPartnerPublicKeysResponse:
      type: object
      title: ListPartnerPublicKeysResponse
      description: Response containing the list of partner public keys for a TMC.
      properties:
        keys:
          type: array
          description: List of partner public keys.
          items:
            $ref: '#/components/schemas/PartnerPublicKeyInfo'
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer