Lesan AI Documentation

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

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 "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"
  }'

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, or the Error Codes reference for authentication error details.

Authentication