Authentication

Overview

All API requests to Smallest Self-Host require authentication using your license key. This ensures only authorized clients can access the speech-to-text service.

Authentication Method

Smallest Self-Host uses Bearer token authentication with your license key.

Authorization Header

Include your license key in the Authorization header:

1
Authorization: Token YOUR_LICENSE_KEY

Example Requests

$
curl -X POST http://localhost:7100/v1/listen \
>
  -H "Authorization: Token ${LICENSE_KEY}" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "url": "https://example.com/audio.wav"
>
  }'

Response Codes

Error Responses

401 Unauthorized

1
{
2
  "error": "Invalid license key",
3
  "code": "INVALID_LICENSE"
4
}

Solutions:

• Verify license key is correct
• Check Authorization header format
• Ensure license hasn’t expired

403 Forbidden

1
{
2
  "error": "License expired",
3
  "code": "LICENSE_EXPIRED",
4
  "expires_at": "2024-12-31T23:59:59Z"
5
}

Solutions:

• Renew license with Smallest.ai
• Contact support@smallest.ai

429 Rate Limited

1
{
2
  "error": "Rate limit exceeded",
3
  "code": "RATE_LIMIT_EXCEEDED",
4
  "retry_after": 60
5
}

Solutions:

• Wait and retry after specified seconds
• Implement exponential backoff
• Contact support for higher limits

Security Best Practices

$
export LICENSE_KEY="your-license-key-here"

1
const API_URL = "https://api.example.com";

1
apiServer:
2
  tls:
3
    enabled: true
4
    certSecretName: "api-server-tls"

1
from ratelimit import limits, sleep_and_retry
2
3
@sleep_and_retry
4
@limits(calls=100, period=60)
5
def call_api():
6
    response = requests.post(...)
7
    return response

SDK Integration

Python SDK

$
pip install smallest-client

1
from smallest import Client
2
3
client = Client(
4
    api_url="http://localhost:7100",
5
    license_key="your-license-key-here"
6
)
7
8
result = client.transcribe_url("https://example.com/audio.wav")
9
print(result.text)

JavaScript SDK

$
npm install @smallest/client

1
import { SmallestClient } from '@smallest/client';
2
3
const client = new SmallestClient({
4
  apiUrl: 'http://localhost:7100',
5
  licenseKey: 'your-license-key-here'
6
});
7
8
const result = await client.transcribeUrl('https://example.com/audio.wav');
9
console.log(result.text);

Testing Authentication

Health Check (No Auth Required)

$
curl http://localhost:7100/health

Expected response:

1
{
2
  "status": "healthy"
3
}

Verify License Key

$
curl -X POST http://localhost:7100/v1/listen \
>
  -H "Authorization: Token ${LICENSE_KEY}" \
>
  -H "Content-Type: application/json" \
>
  -d '{"url": "https://example.com/test.wav"}'

Successful authentication returns transcription results.

What’s Next?