Authentication

Authenticate to the Polimorf runtime API with a workspace API key sent as a bearer token, and manage scopes safely.

The public runtime API authenticates with a workspace API key, not a user session. Every request carries the key as a bearer token.

API keys

A key belongs to a workspace and is created and revoked from the Polimorf dashboard (or the API-keys admin API).
Keys are prefixed csk_live_ followed by a random secret, e.g. csk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
The full secret is shown once, at creation time. Store it in a secret manager or environment variable — Polimorf keeps only a hash and cannot show it again.

Treat an API key like a password. Never commit it to source control, embed it in a browser bundle, or expose it to end users. Call Polimorf from your server, not from client-side code.

Sending the key

Send the key in the Authorization header as a bearer token on every request:

POST /runtime/execute HTTP/1.1
Host: api.polimorf.app
Authorization: Bearer csk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

With the SDK

The SDK attaches the header for you. Provide the key explicitly or via the POLIMORF_API_KEY environment variable — an explicit option always wins:

import { createClient } from '@polimorfapp/sdk';

// Read from POLIMORF_API_KEY in the environment (recommended):
const client = createClient();

// …or pass it explicitly:
const explicit = createClient({ apiKey: 'csk_live_…' });

createClient() throws immediately if no key is configured, so a misconfiguration fails fast at startup rather than on the first request.

With curl

curl https://api.polimorf.app/runtime/execute \
  -H "Authorization: Bearer $POLIMORF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "openai",
    "model": "gpt-4o",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

Each key carries a set of scopes. The runtime endpoints require the runtime:execute scope — the only scope in the current catalog, and granted by default to every new key. A key created without it is rejected with 403 (FORBIDDEN).

Base URL

Environment	Base URL
Managed (default)	`https://api.polimorf.app`
Self-hosted	your own deployment

The SDK defaults to the managed URL. Point it elsewhere with the baseUrl option or the POLIMORF_BASE_URL environment variable:

const client = createClient({ baseUrl: 'https://api.your-company.internal' });

Authentication failures

Status	Code	Meaning
`401`	`UNAUTHENTICATED`	Missing, malformed, or empty `Authorization` header.
`401`	`INVALID_CREDENTIALS`	The key is unknown, revoked, or does not carry the `csk_live_` prefix.
`403`	`FORBIDDEN`	The key is valid but lacks the required scope.

With the SDK, a 401 is thrown as an AuthenticationError and a 403 as a PermissionDeniedError. See Errors for the full catalog.

Rotating a key

Create a new key in the dashboard.
Roll it out to your environment (POLIMORF_API_KEY).
Revoke the old key. Revocation takes effect immediately — subsequent requests with the old key fail with 401 INVALID_CREDENTIALS.