# Authentication

KrosAI uses API keys to authenticate requests. You can create and manage API keys in the [Dashboard](https://cockpit.krosai.com/dashboard/api-keys).

#### API Key Authentication

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

{% tabs %}
{% tab title="TypeScript" %}

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

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(
    'https://api.krosai.com/v1/phone-numbers',
    headers={'x-api-key': 'kros_live_your_api_key_here'}
)
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X GET "https://api.krosai.com/v1/phone-numbers" \
  -H "x-api-key: kros_live_your_api_key_here"
```

{% endtab %}
{% endtabs %}

#### API Key Format

KrosAI API keys follow this format:

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

{% hint style="info" %}
All API keys are prefixed with `kros_` for easy identification.
{% endhint %}

#### Creating API Keys Via Dashboard

<figure><img src="/files/9eBvJyWRwYzvCHd87Y4w" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

#### Create API key

Go to **Developers** → **API Keys**
{% endstep %}

{% step %}

#### Click Create

Click **Create API Key**
{% endstep %}

{% step %}

#### Name the key

Enter a descriptive name
{% endstep %}

{% step %}

#### Select scopes

Select the required scopes
{% endstep %}

{% step %}

#### Optional: IP restrictions

(Optional) Add IP restrictions
{% endstep %}

{% step %}

#### Optional: expiration

(Optional) Set expiration date
{% endstep %}

{% step %}

#### Finish

Click **Create**

> Important: Copy your API key immediately after creation. For security, we only show the full key once.
> {% endstep %}
> {% endstepper %}

#### 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:**

{% code title="read-only.json" %}

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

{% endcode %}

**Full access for server-side integrations:**

{% code title="full-access.json" %}

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

{% endcode %}

**Voice SDK access only:**

{% code title="voice-sdk.json" %}

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

{% endcode %}

#### IP Restrictions

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

{% code title="allowed\_ips.json" %}

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

{% endcode %}

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

#### Key Rotation

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

{% stepper %}
{% step %}

#### Create new key

Create a new API key with the same scopes
{% endstep %}

{% step %}

#### Update application

Update your application to use the new key
{% endstep %}

{% step %}

#### Verify

Verify the new key works correctly
{% endstep %}

{% step %}

#### Revoke old key

Revoke the old key
{% endstep %}
{% endstepper %}

### Bearer Token Authentication

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

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

{% hint style="info" %}
Bearer tokens are typically used for dashboard access. For server-side integrations, use API keys.
{% endhint %}

### Error Responses

<details>

<summary>Invalid API Key</summary>

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

Status: 401 Unauthorized

</details>

<details>

<summary>Missing API Key</summary>

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

Status: 401 Unauthorized

</details>

<details>

<summary>Insufficient Scope</summary>

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

Status: 403 Forbidden

</details>

<details>

<summary>IP Not Allowed</summary>

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

Status: 403 Forbidden

</details>

<details>

<summary>Key Expired</summary>

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

Status: 401 Unauthorized

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.krosai.com/getting-started/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.