# Authentication

How to authenticate with the Lesan AI API using Bearer API keys and scopes.

All API requests to Lesan AI require authentication using an API key passed in the Authorization header.

> **💡 Tip**
>
> Just want to confirm a key works? See [Step 1 — Verify your API key](/guides/getting-started) in Getting Started for a one-line check.

## Getting Your API Key

To get your API key, you need to create one through the API key management endpoints. API keys are prefixed with `sk_live_` or `sk_test_`.

## Using Your API Key

Include your API key in the Authorization header of every request:

```text
Authorization: Bearer YOUR_API_KEY
```

### Example Request

```curl
curl "https://asr.lesan.ai/v1/transcriptions" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio.mp3",
    "language": "am"
  }'
```

```python
import requests

response = requests.post(
    'https://asr.lesan.ai/v1/transcriptions',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json'
    },
    json={
        'audio_url': 'https://example.com/audio.mp3',
        'language': 'am'
    }
)

print(response.json())
```

```javascript
const response = await fetch('https://asr.lesan.ai/v1/transcriptions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    audio_url: 'https://example.com/audio.mp3',
    language: 'am'
  })
});

const data = await response.json();
console.log(data);
```

## API Key Types

Lesan AI supports two types of API keys:

- **Live keys** (`sk_live_`) — Production keys for server-side use. Never expose these in client-side code.
- **Test keys** (`sk_test_`) — Testing keys with lower rate limits and test data.

## API Key Scopes

API keys can be configured with specific scopes to limit access. Available scopes:

- **read** — Read access to transcription jobs, results, and usage information
- **write** — Submit transcription and translation jobs, manage webhooks
- **admin** — Full access including key management and account settings

When creating an API key, assign only the scopes your application needs. This follows the principle of least privilege and limits the impact if a key is compromised.

## Environments

API keys are scoped to a specific environment. Use different keys for each stage of development:

- **Live** (`sk_live_`) — Production environment. Requests are billed and rate-limited at production levels.
- **Test** (`sk_test_`) — Testing environment. Requests use test data and have lower rate limits.

## IP Whitelisting

For additional security, you can restrict API keys to specific IP addresses. When IP whitelisting is enabled, requests from non-whitelisted IPs will receive a 403 error.

```json
# When creating or updating an API key, specify allowed IPs:
{
  "name": "Production Server",
  "scopes": ["transcribe", "transcribe:read"],
  "allowed_ips": ["203.0.113.10", "203.0.113.11"],
  "allowed_origins": ["https://app.example.com"]
}
```

## Origin Restrictions

Publishable keys should be restricted to specific origins (domains) to prevent unauthorized use from other websites. Set allowed origins when creating the key.

## Key Expiration

API keys can be configured with an expiration date. Expired keys return a 401 error with code `expired_api_key`. Set up key rotation before expiration to avoid service interruption.

## Security Best Practices

- Never commit API keys to version control
- Use environment variables to store keys
- Rotate keys regularly — especially if team members leave
- Use different keys for different environments (dev, test, production)
- Use restricted keys with minimal scopes for each service
- Enable IP whitelisting for server-side keys
- Set expiration dates and rotate before they expire
- Monitor key usage for suspicious activity through the usage endpoint

For more details, see the [API Reference](/api-reference), or the [Error Codes](/guides/error-codes) reference for authentication error details.