Skip to main content

​
Authentication

The Kallglot API uses API keys to authenticate requests. Create your developer account at kallglot.com, then create and manage API keys in the Developer Portal.

​
API Keys

API keys are used to authenticate all requests to the Kallglot API. Each key is scoped to a specific organization and can have different permission levels.

​
Key Types

TypePrefixUsage
Livesk_live_Production environment
Testsk_test_Development and testing
Never expose your API keys in client-side code. API keys should only be used in server-side applications. For browser-based applications, use session tokens provided by your backend.

​
Making Authenticated Requests

Include your API key in the Authorization header using the Bearer token format: 
curl https://api.kallglot.com/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key"

​
Request Headers

HeaderRequiredDescription
AuthorizationYesBearer token with your API key
Content-TypeYesapplication/json for POST/PUT/PATCH requests
Idempotency-KeyRecommendedUnique key to ensure idempotent requests

​
WebSocket Authentication

WebSocket connections use session tokens instead of API keys. When you create a session, the response includes a stream.token that authenticates the WebSocket connection: 
// 1. Create session with API key (server-side)
const session = await fetch('https://api.kallglot.com/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mode: 'bidirectional_translation',
    source_language: 'de',
    target_language: 'en'
  })
}).then(r => r.json());

// 2. Connect to WebSocket with session token (can be client-side)
const ws = new WebSocket(session.stream.url, {
  headers: {
    'Authorization': `Bearer ${session.stream.token}`
  }
});

​
Token Expiration

Session tokens expire after 1 hour by default. The stream.expires_at field indicates when the token expires. For long-running sessions, the WebSocket connection remains active even after the token expires - the token is only validated at connection time.

​
API Key Permissions

API keys can have different permission scopes:
PermissionDescription
sessions:readRetrieve session information
sessions:writeCreate and end sessions
recordings:readAccess recordings
recordings:deleteDelete recordings
analysis:readAccess call analysis
analysis:writeRequest call analysis
webhooks:manageManage webhook endpoints

​
Creating Scoped Keys

When creating an API key, you can limit its permissions: 
// Full access key (default)
const fullKey = await createApiKey({ scopes: ['*'] });

// Read-only key
const readKey = await createApiKey({
  scopes: ['sessions:read', 'recordings:read']
});

// Session management only
const sessionKey = await createApiKey({
  scopes: ['sessions:read', 'sessions:write']
});

​
Security Best Practices

Create new API keys periodically and revoke old ones. This limits the impact of any key that may have been compromised.
Never hardcode API keys in your source code. Use environment variables:
export KALLGLOT_API_KEY=sk_live_your_api_key

const apiKey = process.env.KALLGLOT_API_KEY;
Test keys (sk_test_) don’t incur charges and are rate-limited differently. Use them during development.
Check the Developer Portal regularly for unusual API activity. Set up alerts for high usage patterns.
If you suspect a key has been compromised, revoke it immediately in the Developer Portal and create a new one.

​
Error Responses

Authentication errors return a 401 Unauthorized response: 
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "type": "authentication_error"
  }
}
Error CodeDescription
invalid_api_keyThe API key is malformed or doesn’t exist
expired_api_keyThe API key has expired
revoked_api_keyThe API key has been revoked
insufficient_permissionsThe API key lacks required permissions

​
Rate Limiting by Key Type

Key TypeRequests/minuteConcurrent Sessions
Test605
Live (Starter)12010
Live (Pro)60050
Live (Enterprise)CustomCustom
See Rate Limits for detailed information about rate limiting.