Authentication

Every programmatic call uses an organization API key. Sign up at kallglot.com, open the Developer Portal, and create keys per environment (sk_live_* vs sk_test_*).

API Keys

Every API key belongs to a single organization.

Key Types

Type	Prefix	Usage
Live	`sk_live_`	Production traffic
Test	`sk_test_`	Test or sandbox traffic

Why calls fail (`401`, `402`, `403`)

Typical gate checks: unknown or revoked keys, wrong live/test environment, inactive subscription, or exhausted API credits. See Errors when wiring retries.

Never expose your API keys in client-side code. Use API keys only in trusted server-side environments. Browser and mobile clients should connect with short-lived session stream tokens created by your backend.

Making Authenticated Requests

Use the Authorization header with a Bearer token:

curl https://api.kallglot.com/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key"

Request Headers

Header	Required	Description
`Authorization`	Yes	Preferred format: `Bearer <api_key>`
`X-API-Key`	No	Alternative to `Authorization`
`Content-Type`	Yes for JSON bodies	Use `application/json` for POST requests
`Idempotency-Key`	Recommended on POST	Prevents duplicate writes on retry

WebSocket Authentication

WebSocket connections use the session stream token returned by POST /v1/sessions, not your API key.

const session = await fetch('https://api.kallglot.com/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.KALLGLOT_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mode: 'bidirectional_translation',
    source_language: 'de',
    target_language: 'en'
  })
}).then((response) => response.json());

const ws = new WebSocket(
  `${session.stream.url}?token=${session.stream.token}`
);

That JSON body is WebSocket-only (no PSTN leg). For Twilio, Telnyx, or SIP, add routing on POST /v1/sessions as documented in Create Session—do not use a nested provider object.

Token Expiration

Stream tokens expire after 5 minutes. The stream.expires_at field tells you exactly when the token expires. Token expiry is checked only when the WebSocket connects, so an already-connected stream stays active after that point.

API Key Permissions

API keys can be scoped to the smallest permission set your application needs:

Permission	Description
`sessions:read`	Retrieve session details
`sessions:write`	Create and end sessions
`recordings:read`	Access recordings
`analysis:read`	Retrieve analysis results
`analysis:write`	Request session analysis
`webhooks:manage`	Manage webhook endpoints

New keys are created with the full standard scope set listed above so integrations work out of the box; prefer the smallest viable set whenever you can customize scopes.

Response Headers

Authenticated HTTP responses may include these headers:

Header	Description
`X-Request-ID`	Stable request identifier for support and debugging
`X-RateLimit-Limit`	Maximum requests allowed in the current rate-limit window
`X-RateLimit-Remaining`	Requests remaining in the current rate-limit window
`X-RateLimit-Reset`	Unix timestamp when the current rate-limit window resets
`X-API-Credits-Remaining`	Remaining API credits for the organization
`X-API-Credits-Used`	API credits used in the current billing period

For billable write requests, the credit headers reflect the post-request balance when the request succeeds.

Authentication And Billing Errors

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_api_credits",
    "message": "API credits exhausted. Purchase more credits to continue.",
    "request_id": "req_123"
  }
}

Status	Code	Meaning
`401`	`api_key_invalid`	The API key is missing, malformed, or unknown
`401`	`api_key_expired`	The API key has expired
`401`	`api_key_revoked`	The API key has been revoked
`401`	`api_key_wrong_environment`	A test key was used against live, or vice versa
`403`	`organization_inactive`	The organization subscription is inactive
`402`	`insufficient_api_credits`	The organization has no API credits remaining
`403`	`insufficient_permissions`	The key lacks a required permission (scopes); this is unrelated to `402` (billing / credits exhaustion)

Examples: POST /v1/sessions needs sessions:write. A key missing that scope receives 403 even when credits are available (402).

Security Best Practices

Rotate keys regularly

Create new API keys periodically and revoke old ones to reduce exposure if a key is leaked.

Use environment variables

Store API keys in environment variables or a secret manager, never in source control.

export KALLGLOT_API_KEY=sk_live_your_api_key

Separate test and live keys

Live keys should only be used against the live API environment. Test keys should only be used in test or sandbox environments.

Monitor usage and credits

Watch the Developer Portal for unusual API activity, rate-limit pressure, and low API-credit balances.

Revoke compromised keys immediately

If a key may have been exposed, revoke it immediately and replace it with a new scoped key.

See Error Codes for the full error catalog and Rate Limits for throughput limits and retry guidance.

​Authentication

​API Keys

​Key Types

​Why calls fail (401, 402, 403)

​Making Authenticated Requests

​Request Headers

​WebSocket Authentication

​Token Expiration

​API Key Permissions

​Response Headers

​Authentication And Billing Errors

​Security Best Practices

Authentication

API Keys

Key Types

Why calls fail (`401`, `402`, `403`)

Making Authenticated Requests

Request Headers

WebSocket Authentication

Token Expiration

API Key Permissions

Response Headers

Authentication And Billing Errors

Security Best Practices