> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tofrom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Secure your API requests with proper authentication

## Overview

Our API uses bearer token authentication. You'll need to include your API key in the `Authorization` header of every request.

## Getting your API key

1. Log into your dashboard
2. Navigate to your workspace settings
3. Click on "API Keys" section
4. Click "Generate new API key"
5. Copy and securely store your key

<Warning>
  API keys are shown only once. If you lose your key, you'll need to generate a new one.
</Warning>

## Using your API key

Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.yourdomain.com/api/messages \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.yourdomain.com/api/messages', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://api.yourdomain.com/api/messages', headers=headers)
  ```
</CodeGroup>

## Security best practices

### 1. Keep keys secret

Never expose API keys in:

* Client-side code
* Public repositories
* Log files
* Error messages

### 2. Use environment variables

Store API keys in environment variables:

```javascript theme={null}
// Good ✅
const apiKey = process.env.MESSAGING_API_KEY;

// Bad ❌
const apiKey = 'sk_live_abcd1234...';
```

### 3. Rotate keys regularly

Periodically rotate your API keys:

1. Generate a new key
2. Update your application
3. Revoke the old key

### 4. Use separate keys per environment

Create different keys for:

* Development
* Staging
* Production

### 5. Monitor key usage

Regularly review your API key usage in the dashboard to detect any unusual activity.

## Revoking API keys

If a key is compromised:

1. Go to your workspace settings
2. Find the compromised key
3. Click "Revoke"
4. Generate a new key immediately

<Note>
  Revoked keys stop working immediately. Update your applications before revoking keys in production.
</Note>

## API key permissions

API keys inherit the permissions of the workspace they're created in. Each key can:

* Send messages
* Retrieve message history
* Access workspace settings
* Manage phone numbers

## Troubleshooting

### 401 Unauthorized

This error means your API key is invalid or missing:

```json theme={null}
{
  "error": "unauthorized",
  "detail": "Invalid or missing API key"
}
```

**Solutions:**

* Check that the key is included in the header
* Verify the key hasn't been revoked
* Ensure you're using the correct key format: `Bearer YOUR_KEY`

### 403 Forbidden

This error means your key doesn't have permission for this action:

```json theme={null}
{
  "error": "forbidden",
  "detail": "Insufficient permissions for this resource"
}
```

**Solutions:**

* Verify you're accessing the correct workspace
* Check that your workspace has the required features enabled

## Session authentication

Some endpoints (primarily UI endpoints) use session authentication instead of API keys. These are typically used by our web dashboard and require user login.

## Next steps

* [Send your first message](/quickstart)
* [Handle errors properly](/guides/error-handling)
* [Understand rate limits](/guides/rate-limits)