Authentication

KrosAI uses API keys to authenticate requests. You can create and manage API keys in the Dashboard.

API Key Authentication

Include your API key in the x-api-key header of every request:

TypeScript

const response = await fetch('https://api.krosai.com/v1/phone-numbers', {
  headers: {
    'x-api-key': 'kros_live_your_api_key_here',
  },
});

Python

cURL

API Key Format

KrosAI API keys follow this format:

kros_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     │
     └── Environment: "live" for production

All API keys are prefixed with kros_ for easy identification.

Creating API Keys Via Dashboard

1

Create API key

Go to Developers → API Keys

2

Click Create

Click Create API Key

3

Name the key

Enter a descriptive name

4

Select scopes

Select the required scopes

5

Optional: IP restrictions

(Optional) Add IP restrictions

6

Optional: expiration

(Optional) Set expiration date

7

Finish

Click Create

Important: Copy your API key immediately after creation. For security, we only show the full key once.

API Key Properties

Property	Description
Name	Descriptive name for identification
Scopes	Permissions granted to the key
Allowed IPs	Optional IP allowlist for extra security
Expires At	Optional expiration date
Created At	When the key was created
Last Used	Last time the key was used

Scopes

Scopes control what actions an API key can perform. Use the principle of least privilege—only grant scopes that are needed.

Available Scopes

Scope	Description
numbers:read	View phone numbers
numbers:write	Purchase, configure, and release phone numbers
endpoints:read	View endpoints
endpoints:write	Create, update, and delete endpoints
calls:read	View call logs and recordings
calls:write	Initiate outbound calls, hangup calls
webhooks:read	View webhooks
webhooks:write	Create, update, and delete webhooks
billing:read	View balance and transactions
billing:write	Add credits, manage subscriptions
api-keys:read	View API keys
api-keys:write	Create, update, and revoke API keys
voice:connect	Use the Voice SDK to connect calls

Scope Examples

Read-only access for analytics:

read-only.json

{
  "scopes": ["calls:read", "numbers:read", "billing:read"]
}

Full access for server-side integrations:

full-access.json

{
  "scopes": [
    "numbers:read", "numbers:write",
    "endpoints:read", "endpoints:write",
    "calls:read", "calls:write",
    "webhooks:read", "webhooks:write"
  ]
}

Voice SDK access only:

voice-sdk.json

{
  "scopes": ["voice:connect", "calls:read"]
}

IP Restrictions

For additional security, you can restrict API key usage to specific IP addresses:

allowed_ips.json

{
  "allowed_ips": ["203.0.113.50", "198.51.100.0/24"]
}

Requests from non-allowed IPs will receive a 403 Forbidden response.

Key Rotation

We recommend rotating API keys regularly. To rotate a key:

1

Create new key

Create a new API key with the same scopes

2

Update application

Update your application to use the new key

3

Verify

Verify the new key works correctly

4

Revoke old key

Revoke the old key

Bearer Token Authentication

For browser-based applications using the KrosAI Dashboard, we also support Bearer token authentication using JWTs:

curl -X GET "https://api.krosai.com/v1/phone-numbers" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Bearer tokens are typically used for dashboard access. For server-side integrations, use API keys.

Error Responses

Invalid API Key

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Status: 401 Unauthorized

Missing API Key

{
  "error": "Missing API key",
  "code": "MISSING_API_KEY"
}

Status: 401 Unauthorized

Insufficient Scope

{
  "error": "API key lacks required scope: calls:write",
  "code": "INSUFFICIENT_SCOPE"
}

Status: 403 Forbidden

IP Not Allowed

{
  "error": "Request from IP 192.168.1.1 not allowed",
  "code": "IP_NOT_ALLOWED"
}

Status: 403 Forbidden

Key Expired

{
  "error": "API key has expired",
  "code": "KEY_EXPIRED"
}

Status: 401 Unauthorized