Skip to main content

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

CodeStatusDescription
200OKRequest successful
400Bad RequestInvalid request parameters
401UnauthorizedInvalid or missing license key
403ForbiddenLicense expired or quota exceeded
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error
503Service UnavailableService temporarily unavailable

Error Responses

401 Unauthorized

{
  "error": "Invalid license key",
  "code": "INVALID_LICENSE"
}
Solutions:
  • Verify license key is correct
  • Check Authorization header format
  • Ensure license hasn’t expired

403 Forbidden

{
  "error": "License expired",
  "code": "LICENSE_EXPIRED",
  "expires_at": "2024-12-31T23:59:59Z"
}
Solutions:

429 Rate Limited

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}
Solutions:
  • Wait and retry after specified seconds
  • Implement exponential backoff
  • Contact support for higher limits

Security Best Practices

Never hardcode license keys in source code.Use environment variables:
export LICENSE_KEY="your-license-key-here"
Or secret managers:
  • AWS Secrets Manager
  • HashiCorp Vault
  • Kubernetes Secrets
Always use HTTPS for API requests in production:
const API_URL = "https://api.example.com";
Configure TLS:
apiServer:
  tls:
    enabled: true
    certSecretName: "api-server-tls"
Implement key rotation policy:
  • Rotate keys every 90 days
  • Use different keys for dev/staging/prod
  • Revoke compromised keys immediately
Track API usage to detect anomalies:
  • Unusual traffic patterns
  • Failed authentication attempts
  • Quota approaching limits
Add client-side rate limiting:
from ratelimit import limits, sleep_and_retry

@sleep_and_retry
@limits(calls=100, period=60)
def call_api():
    response = requests.post(...)
    return response

SDK Integration

Python SDK

pip install smallest-client
from smallest import Client

client = Client(
    api_url="http://localhost:7100",
    license_key="your-license-key-here"
)

result = client.transcribe_url("https://example.com/audio.wav")
print(result.text)

JavaScript SDK

npm install @smallest/client
import { SmallestClient } from '@smallest/client';

const client = new SmallestClient({
  apiUrl: 'http://localhost:7100',
  licenseKey: 'your-license-key-here'
});

const result = await client.transcribeUrl('https://example.com/audio.wav');
console.log(result.text);
SDKs automatically handle authentication, retries, and error handling.

Testing Authentication

Health Check (No Auth Required)

curl http://localhost:7100/health
Expected response:
{
  "status": "healthy"
}

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?