openapi: 3.2.0
info:
  title: KnoxCall Client Management Account API
  version: '1.0'
  description: 'The KnoxCall Client Management API provides programmatic access to manage your API gateway

    resources including routes, secrets, clients, environments, webhooks, and API keys. ## Authentication


    All requests must include an OAuth 2.1 access token **or** a legacy API key. The

    recommended path for new integrations is the first-party SDKs, which mint, cache, and

    refresh OAuth tokens for you (start with `knoxcall login` on a developer machine, or

    `KNOXCALL_CLIENT_ID` / `KNOXCALL_CLIENT_SECRET` in CI). You can authenticate using any of:


    - **Authorization header (OAuth 2.1 bearer token — recommended)**: `Authorization: Bearer `

    - **Authorization header (legacy API key)**: `Authorization: Bearer tk_xxx_yyy`

    - **x-api-key header (legacy API key)**: `x-api-key: tk_xxx_yyy`


    OAuth 2.1 access tokens (`kc_` prefix) are minted at the root-host token endpoint

    `https://api.knoxcall.com/oauth/token` (not under `/v1`) using the `client_credentials`

    or `authorization_code` grant. See the `OAuth2` security scheme and the `/oauth/*`

    endpoints. Some resources that are managed exclusively through OAuth reject API-key auth

    with a `403 use_oauth` error. Long-lived API keys remain fully supported. They come in three types:

    - **Standard keys** (`tk_` prefix) are used on the production API (`api.knoxcall.com`). - **Test keys** (`tk_` prefix, type=test) are used on the sandbox API (`sandbox.knoxcall.com`). - **Enterprise Access Keys** (`AKE` prefix) follow the format `AKE[16chars]:[40chars]`. Using a test key on the production API (or vice versa) will return a `403 wrong_key_type` error. ## Request IDs


    Every response — success or error — includes an `X-Request-Id` response header (a UUID). Its value is identical to the `request_id` field in the response body (`meta.request_id`

    on success, `error.request_id` on error). Quote it when contacting support. ## API Versioning


    The API is versioned on two axes:


    - **Major version — the `/v1` path prefix.** Breaking changes ship under a new major

    (`/v2`). `/v1` never receives a breaking change. - **Minor version — the `KnoxCall-Version` header (dated, `YYYY-MM-DD`).** Send

    `KnoxCall-Version: 2026-08-05` to pin the behaviour of a specific dated release. Omit

    the header to get the newest minor version. Every response echoes the resolved version

    back in a `KnoxCall-Version` response header. Within a major version, **additive changes are not breaking** and may appear without a new

    dated version: new endpoints, new optional request fields, new response fields, new

    `error.type` values, and new enum members. Clients must tolerate unknown response fields

    and unknown `error.type` values (see the `ErrorResponse` schema). An **unknown or malformed** `KnoxCall-Version` value returns `400` with

    `error.type: invalid_api_version`. ## Rate Limiting


    API keys can have optional rate limits configured. When a limit is configured, the

    following headers are emitted on **every** response (not only `429`s):

    - `X-RateLimit-Limit` -- maximum requests allowed per window

    - `X-RateLimit-Remaining` -- remaining requests in the current window

    - `X-RateLimit-Reset` -- epoch seconds at which the window resets


    When the limit is exceeded the API returns `429` (`rate_limit_exceeded` / `rate_limited`)

    and additionally sets `Retry-After` (seconds until the window resets). ## DPoP sender-constrained tokens, and the server nonce


    A token minted with a `cnf.jkt` binding (DPoP, RFC 9449) requires a `DPoP` proof header

    on every request, signed over the request''s method and canonical public URL. **Every response to a request that carried a `DPoP` header also carries a

    `DPoP-Nonce` response header** -- mints, refusals and successful calls alike, on

    `POST /oauth/token`, `/v1`, the tenant data plane, the self-hosted proxy and the AI

    gateway. The value is stateless and changes every minute; the server accepts the current

    and the previous minute''s, so a nonce is good for 60-120 seconds.'
  contact:
    name: KnoxCall Support
    url: https://knoxcall.com
    email: support@knoxcall.com
  license:
    name: Proprietary
    url: https://knoxcall.com/terms
servers:
- url: https://api.knoxcall.com/v1
  description: Production
- url: https://sandbox.knoxcall.com/v1
  description: Sandbox (test keys only)
security:
- OAuth2: []
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Account
  description: Retrieve account information and usage metrics.
paths:
  /account:
    get:
      operationId: getAccount
      summary: Get account info
      description: Returns general information about the authenticated account including subscription details.
      tags:
      - Account
      responses:
        '200':
          description: Account information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Account'
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /account/usage:
    get:
      operationId: getAccountUsage
      summary: Get current usage
      description: Returns the current billing period usage including API call counts and resource limits for your plan.
      tags:
      - Account
      responses:
        '200':
          description: Current usage data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AccountUsage'
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    NotFound:
      description: The requested resource was not found.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        KnoxCall-Version:
          $ref: '#/components/headers/KnoxCall-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: not_found
              message: Route not found.
              request_id: 550e8400-e29b-41d4-a716-446655440000
    InternalError:
      description: An unexpected server error occurred.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        KnoxCall-Version:
          $ref: '#/components/headers/KnoxCall-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: internal_error
              message: An unexpected error occurred.
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Unauthorized:
      description: Authentication is required or the provided API key is invalid.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        KnoxCall-Version:
          $ref: '#/components/headers/KnoxCall-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_key:
              summary: No API key provided
              value:
                error:
                  type: authentication_required
                  message: 'API key is required. Use Authorization: Bearer <api_key> or x-api-key header.'
                  request_id: 550e8400-e29b-41d4-a716-446655440000
            invalid_key:
              summary: Invalid API key
              value:
                error:
                  type: invalid_api_key
                  message: Invalid API key.
                  request_id: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    Account:
      type: object
      description: Account information and subscription details.
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
          description: Unique account slug used in subdomain routing.
          example: acme-corp
        name:
          type: string
          description: Account display name.
          example: Acme Corp
        region:
          type:
          - string
          - 'null'
          description: Primary deployment region.
          example: us-east-1
        subscription_plan:
          type: string
          enum:
          - starter
          - professional
          - enterprise
          description: Current subscription plan.
          example: professional
        subscription_status:
          type:
          - string
          - 'null'
          enum:
          - trialing
          - active
          - past_due
          - canceled
          - paused
          - unpaid
          - null
          description: Current subscription status.
          example: active
        trial_start_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Trial period start date.
        trial_end_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Trial period end date.
        subscription_current_period_start:
          type:
          - string
          - 'null'
          format: date-time
          description: Current billing period start date.
        subscription_current_period_end:
          type:
          - string
          - 'null'
          format: date-time
          description: Current billing period end date.
        subscription_cancel_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Scheduled cancellation date, if any.
        created_at:
          type: string
          format: date-time
          example: '2025-01-01T00:00:00.000Z'
    RequestMeta:
      type: object
      description: Metadata included with every API response.
      properties:
        request_id:
          type: string
          format: uuid
          description: Unique identifier for this API request, useful for support and debugging.
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
      - request_id
    AccountUsage:
      type: object
      description: Current billing period usage and plan limits.
      properties:
        billing_period:
          type: object
          description: Current billing period dates.
          properties:
            year:
              type: integer
              example: 2025
            month:
              type: integer
              example: 3
            start:
              type:
              - string
              - 'null'
              format: date-time
              description: Billing period start date.
            end:
              type:
              - string
              - 'null'
              format: date-time
              description: Billing period end date.
        api_calls:
          type: object
          description: API call usage for the current billing period.
          properties:
            used:
              type: integer
              description: Number of API calls made this period.
              example: 12450
            limit:
              type:
              - integer
              - 'null'
              description: Maximum API calls allowed per period (null for unlimited).
              example: 50000
            percentage:
              type: integer
              description: Percentage of the limit used.
              example: 25
        resources:
          type: object
          description: Resource counts and plan limits.
          properties:
            routes:
              $ref: '#/components/schemas/ResourceUsage'
            secrets:
              $ref: '#/components/schemas/ResourceUsage'
            clients:
              $ref: '#/components/schemas/ResourceUsage'
            environments:
              $ref: '#/components/schemas/ResourceUsage'
        plan:
          type: string
          description: Current subscription plan.
          example: professional
        status:
          type: string
          description: Current subscription status.
          example: active
    ResourceUsage:
      type: object
      description: Usage count and limit for a resource type.
      properties:
        used:
          type: integer
          description: Number of resources currently in use.
          example: 5
        limit:
          type:
          - integer
          - 'null'
          description: Maximum allowed by the plan (null for unlimited).
          example: 25
    ErrorResponse:
      type: object
      description: Standard error response envelope.
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: 'Machine-readable error type. The set is OPEN — endpoints define specific types beyond the common ones below, so clients should branch on the types they know and fall back to the HTTP status class for anything unrecognized. Common values: authentication_required, invalid_api_key, wrong_key_type, subscription_inactive, rate_limit_exceeded, validation_error, forbidden, not_found, method_not_allowed (405, carries Allow), conflict, in_use, plan_limit, plan_feature, internal_error, dependency_unavailable (503, carries Retry-After), invalid_request, invalid_definition, not_cancellable, invalid_idempotency_key, idempotency_key_reuse, request_in_progress, system_client_protected, use_oauth, use_dpop_nonce (401 on /v1 and the data plane, 400 on POST /oauth/token; see "DPoP sender-constrained tokens").'
              example: validation_error
            message:
              type: string
              description: Human-readable error message.
              example: name and target_base_url are required.
            request_id:
              type: string
              format: uuid
              description: Unique identifier for this request.
              example: 550e8400-e29b-41d4-a716-446655440000
          required:
          - type
          - message
          - request_id
      required:
      - error
  headers:
    KnoxCall-Version:
      description: 'The dated API version (`YYYY-MM-DD`) that served this response. Equals the value

        of the `KnoxCall-Version` request header when supplied, otherwise the newest version.

        '
      schema:
        type: string
        pattern: ^\d{4}-\d{2}-\d{2}$
      example: '2026-08-05'
    X-Request-Id:
      description: 'Unique identifier for this request (UUID). Present on **every** response and equal

        to the `request_id` field in the response body. Quote it when contacting support.

        '
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'OAuth 2.1 authentication — recommended for new integrations. Access tokens

        (`kc_` prefix) are minted at the root-host token endpoint

        `https://api.knoxcall.com/oauth/token` and passed as `Authorization: Bearer <access_token>`.

        Public clients must use PKCE with the `authorization_code` grant; confidential

        clients may use `client_credentials`. The first-party SDKs and the

        `knoxcall login` CLI handle token minting, caching, refresh, and DPoP for you.

        '
      flows:
        clientCredentials:
          tokenUrl: https://api.knoxcall.com/oauth/token
          refreshUrl: https://api.knoxcall.com/oauth/token
          scopes:
            routes:read: Read routes.
            routes:write: Create, update, and delete routes.
            secrets:read: Read secret metadata. Does NOT include retrieving a live OAuth2 access token.
            secrets:oauth_token: Retrieve a live upstream OAuth2 access token (GET /v1/secrets/{id}/oauth2/token). Distinct from secrets:read because the call refreshes the credential at the provider.
            secrets:write: Create, update, and delete secrets.
            vaults:detokenize: Turn a vault token back into its original value. Required by GET /v1/vaults/{vault}/tokens/{token}, by a token template reference in a /v1/proxy body, and by creating a `detokenize` route action. Distinct from vaults:read, which lists vaults and token metadata and never returns a value.
            transit:decrypt: Open a portable `kc:` ciphertext with a tenant transit key. Required by creating a `decrypt` route action, which stores a standing instruction to open every matching field on every later request through that route. It is the same capability name the policy engine uses for POST /v1/decrypt. No routes scope satisfies it — managing a route is not permission to open the data flowing through it.
            proxy:invoke: Call the one-shot ephemeral proxy (any method on /v1/proxy). Required for EVERY verb — the proxy is one capability behind one handler, and a bodyless GET spends an escrowed credential exactly as a POST does. Neither proxy:read nor proxy:write satisfies it.
            clients:read: Read clients.
            clients:write: Manage clients.
            webhooks:write: Manage webhooks.
            workflows:write: Manage and execute workflows.
            '*:*': Full access (all scopes).
        authorizationCode:
          authorizationUrl: https://api.knoxcall.com/oauth/authorize
          tokenUrl: https://api.knoxcall.com/oauth/token
          refreshUrl: https://api.knoxcall.com/oauth/token
          scopes:
            routes:read: Read routes.
            routes:write: Create, update, and delete routes.
            secrets:read: Read secret metadata. Does NOT include retrieving a live OAuth2 access token.
            secrets:oauth_token: Retrieve a live upstream OAuth2 access token (GET /v1/secrets/{id}/oauth2/token). Distinct from secrets:read because the call refreshes the credential at the provider.
            secrets:write: Create, update, and delete secrets.
            vaults:detokenize: Turn a vault token back into its original value. Required by GET /v1/vaults/{vault}/tokens/{token}, by a token template reference in a /v1/proxy body, and by creating a `detokenize` route action. Distinct from vaults:read, which lists vaults and token metadata and never returns a value.
            transit:decrypt: Open a portable `kc:` ciphertext with a tenant transit key. Required by creating a `decrypt` route action, which stores a standing instruction to open every matching field on every later request through that route. It is the same capability name the policy engine uses for POST /v1/decrypt. No routes scope satisfies it — managing a route is not permission to open the data flowing through it.
            proxy:invoke: Call the one-shot ephemeral proxy (any method on /v1/proxy). Required for EVERY verb — the proxy is one capability behind one handler, and a bodyless GET spends an escrowed credential exactly as a POST does. Neither proxy:read nor proxy:write satisfies it.
            clients:read: Read clients.
            clients:write: Manage clients.
            webhooks:write: Manage webhooks.
            workflows:write: Manage and execute workflows.
            '*:*': Full access (all scopes).
    PhantomToken:
      type: http
      scheme: bearer
      description: "The AI **data plane** credential — a `kp_`-prefixed capability token, not a\nManagement API credential. It is minted per agent (or per MCP resource) at\n`POST /v1/ai-gateway/agents/{agentId}/tokens`, or exchanged from a CI workload's\nOIDC token at `POST /v1/oauth/token`, and it is the ONLY credential `/v1/ai/*`\naccepts: an OAuth `kc_` access token or a `tk_` API key is refused there, and a\n`kp_` token is refused on `api.knoxcall.com`.\n\nThree header spellings are accepted, so an existing provider SDK can be pointed at\nthe agent URL without rewriting its auth:\n\n    Authorization: Bearer kp_live_a_...\n    x-api-key: kp_live_a_...\n    x-knox-ai-key: kp_live_a_...\n\n`kp_live_` is refused on the sandbox host and `kp_test_` on the Live host — the env\nsegment is enforced, not cosmetic. DPoP-bound tokens additionally require a valid\n`DPoP` proof header on every request, signed over the canonical public URL rather\nthan a rewritten `Host`.\n\nA rejected credential answers `401`/`403` in the data-plane error envelope with the\ncause in `code` and in the `X-Auth-Failure` response header.\n"
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Legacy long-lived API key authentication via the Authorization header.

        Pass your API key as: `Authorization: Bearer tk_xxx_yyy`.


        Standard keys (`tk_` prefix) are accepted on `api.knoxcall.com`.

        Test keys (type=test) are accepted on `sandbox.knoxcall.com`.

        Enterprise Access Keys (`AKE` prefix) are accepted on both.


        Fully supported, but prefer the `OAuth2` scheme (or the SDKs, which handle

        OAuth for you) for new integrations.

        '
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Legacy API key authentication via the `x-api-key` header.

        This is an alternative to Bearer token authentication for clients that cannot

        set the `Authorization` header. Prefer the `OAuth2` scheme for new integrations.

        '
    CapabilityTokenAuth:
      type: http
      scheme: bearer
      description: 'Single-use client capability token (`kct_` prefix), passed as

        `Authorization: Bearer kct_...`. Minted server-side via

        `POST /client-tokens` and bound either to one exact payload + action

        (`decrypt`, `detokenize`) or to one vault + a closed set of page

        origins (`tokenize`). This is NOT an API key — it authenticates only

        the `POST /client/decrypt`, `POST /client/detokenize` and

        `POST /client/tokenize` consume endpoints and is invalidated after its

        first use.

        '