> ## Documentation Index > Fetch the complete documentation index at: https://docs.kataven.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an API key (returns plaintext sk_live_ ONCE) > Mints a new sk_live_ credential. The plaintext value is returned in the response and never again — store it in your secret manager. Requires Hub UI (Zitadel) auth; sk_live_ keys cannot mint other sk_live_ keys. ## OpenAPI ````yaml /api-spec/openapi.yaml post /api/v1/api-keys openapi: 3.1.0 info: contact: name: Kataven url: https://kataven.ai description: | The Kataven Hub API is the management surface for the Kataven voice AI platform. Use it to create and configure voice agents, manage tools and knowledge, wire up telephony, run outbound campaigns, embed the chat widget, and read account-level settings. ## Authentication Two credential shapes are accepted on every protected endpoint: - **`sk_live__`** — long-lived API key. The token self-identifies the account, so `X-Account-ID` is not required. Recommended for SDK / MCP / CI / any server-to-server use. Mint via Hub UI → **Settings → API Keys**. - **Zitadel JWT** (`eyJ…`, ~1h TTL) — interactive admin sessions from the Hub UI. Requires the `X-Account-ID` header for tenant resolution. Public endpoints (`/api/accounts/*`, `/api/login`, the widget auth endpoints under `/api/v1/widget/auth/*`) require no Authorization header. ## Multi-tenancy Every protected request operates on the per-account PostgreSQL database identified by `X-Account-ID` (or by the `sk_live_` prefix). There is no cross-tenant surface; an account is a hard isolation boundary. The reserved account `kataven-admin` is rejected with `403`. ## Base URLs Routes are mounted at both `/` and `/hub-api/` for compatibility. SDKs default to the `/hub-api/` prefix on `hub.kataven.ai`, or `/v1/` on `api.kataven.ai`. license: name: Proprietary title: Kataven Hub API version: 0.2.0 servers: - url: https://api.kataven.ai/v1 description: Production (recommended for SDKs) - url: https://hub.kataven.ai/hub-api/api description: Production (legacy path, kept for back-compat) - url: http://localhost:8081 description: Local development (api-server only) security: - bearerAuth: [] tags: - name: Agents description: >- CRUD for voice agents — the configurable units that hold a system prompt, voice, model, and tool/playbook/FAQ associations. - name: Tools description: Built-in and custom tools an agent can call during a conversation. - name: Playbooks description: >- Reusable knowledge bundles (system prompt fragments + a list of tool names) that can be attached to one or more agents. - name: FAQs description: Question/answer entries surfaced to agents as quick-lookup knowledge. - name: Marketplace description: Browse and install agent templates. - name: Integrations description: >- Third-party integrations (Stripe, Shopify, etc.) — credentials stored encrypted via the Secret Encryptor service. - name: Telephony description: Carrier credentials and phone-number assignment. - name: Calls description: Outbound call origination. - name: Recordings description: Call recording retrieval (presigned URL). - name: Call Limits description: >- Per-tenant cost caps (read-only via SDK — set by the platform team based on plan tier). - name: Campaigns description: Bulk-dial outbound campaigns from CSV. - name: API Keys description: >- sk_live_ server-to-server credentials. CRUD is gated to Hub UI auth (a leaked sk_live_ cannot mint another). - name: Widget Keys description: pk_live_ public identifiers used by the embeddable widget bootstrap. - name: Widget Admin description: Branding + per-agent widget policy. - name: Widget Auth description: >- Public cross-origin auth endpoints called from customer-page widgets (used by `@kataven/client`, not the server SDK). externalDocs: description: '' url: '' paths: /api/v1/api-keys: post: tags: - API Keys summary: Create an API key (returns plaintext sk_live_ ONCE) description: >- Mints a new sk_live_ credential. The plaintext value is returned in the response and never again — store it in your secret manager. Requires Hub UI (Zitadel) auth; sk_live_ keys cannot mint other sk_live_ keys. operationId: postApiV1ApiKeys parameters: - description: Tenant database. Required when using a Zitadel JWT. in: header name: X-Account-ID schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/handlers.CreateApiKeyRequest' description: Key spec summary: body description: Key spec required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/data.CreatedApiKey' description: Created '400': content: application/json: schema: type: string description: Invalid body or name required '401': content: application/json: schema: type: string description: Missing or invalid bearer token '403': content: application/json: schema: type: string description: Requires Hub UI auth '500': content: application/json: schema: type: string description: Database error security: - bearerAuth: [] components: schemas: handlers.CreateApiKeyRequest: properties: expiry: enum: - 30d - 90d - 1y - '' example: 90d type: string name: example: ci-deploy-bot type: string type: object data.CreatedApiKey: properties: created_at: type: string created_by_email: type: string created_by_sub: type: string disabled_at: type: string expires_at: type: string id: type: string key_id: type: string last_used_at: type: string last_used_ip: type: string name: type: string secret_key: description: sk_live__… type: string secret_last4: type: string type: object securitySchemes: bearerAuth: in: header name: Authorization type: apiKey ````