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.
Include your license key in the Authorization header:
Authorization : Token YOUR_LICENSE_KEY
Example Requests
cURL
Python
JavaScript
Go
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"
}'
import requests
LICENSE_KEY = "your-license-key-here"
API_URL = "http://localhost:7100"
headers = {
"Authorization" : f "Token { LICENSE_KEY } " ,
"Content-Type" : "application/json"
}
response = requests.post(
f " { API_URL } /v1/listen" ,
headers = headers,
json = { "url" : "https://example.com/audio.wav" }
)
print (response.json())
const LICENSE_KEY = "your-license-key-here" ;
const API_URL = "http://localhost:7100" ;
const response = await fetch ( ` ${ API_URL } /v1/listen` , {
method: "POST" ,
headers: {
"Authorization" : `Token ${ LICENSE_KEY } ` ,
"Content-Type" : "application/json"
},
body: JSON . stringify ({
url: "https://example.com/audio.wav"
})
});
const result = await response . json ();
console . log ( result );
package main
import (
" bytes "
" encoding/json "
" fmt "
" net/http "
)
func main () {
licenseKey := "your-license-key-here"
apiURL := "http://localhost:7100/v1/listen"
payload := map [ string ] string {
"url" : "https://example.com/audio.wav" ,
}
jsonData , _ := json . Marshal ( payload )
req , _ := http . NewRequest ( "POST" , apiURL , bytes . NewBuffer ( jsonData ))
req . Header . Set ( "Authorization" , "Token " + licenseKey )
req . Header . Set ( "Content-Type" , "application/json" )
client := & http . Client {}
resp , err := client . Do ( req )
if err != nil {
panic ( err )
}
defer resp . Body . Close ()
var result map [ string ] interface {}
json . NewDecoder ( resp . Body ). Decode ( & result )
fmt . Println ( result )
}
Response Codes
Code Status Description 200 OK Request successful 400 Bad Request Invalid request parameters 401 Unauthorized Invalid or missing license key 403 Forbidden License expired or quota exceeded 429 Too Many Requests Rate limit exceeded 500 Internal Server Error Server error 503 Service Unavailable Service 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:
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?