Authentication
ASAS API keys — format, Bearer auth, scopes, test mode, and rotation.
المصادقة
كل استدعاء للواجهة يتطلب مفتاح API صالحاً في ترويسة Authorization. المفاتيح مرتبطة
بمنشأتك، ومحدودة الصلاحيات، وتُعرض مرة واحدة عند إنشائها.
The ASAS API authenticates every request with an API key sent as a Bearer token. Keys belong to your organization, not to an individual user, so usage, quotas, and billing roll up to the org.
Key format
Keys are prefixed by environment and end in a checksum:
| Prefix | Environment | Billing |
|---|---|---|
asas_live_ | Production | Metered against your credit balance |
asas_test_ | Test mode | Tiny throttled quotas, excluded from billing |
asas_live_<32+ base62 chars><crc32 tail>The gateway rejects malformed keys (bad checksum) before touching the database, and
stores only a keyed HMAC hash of your key — never the key itself. Only a
prefix + last 4 is kept for display.
Sending the key
Pass the key as a Bearer token on every request:
curl https://api.asas.flitc.tech/v1/rag/search \
-H "Authorization: Bearer $ASAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "ما هي سياسة الإجازات؟", "mode": "answer" }'The public API accepts only API keys. It never reads cookies and never accepts a dashboard session. Keep the two planes separate: browser code uses the dashboard; servers use API keys.
Scopes
Each key carries scopes; a call is rejected with 403 if the key lacks the scope
for that endpoint.
| Scope | Grants |
|---|---|
tts:speak | POST /v1/tts, /v1/tts/stream, WS /v1/tts/realtime |
stt:transcribe | POST /v1/stt/transcriptions, WS /v1/stt/realtime |
rag:query | POST /v1/rag/search, RAG document + job endpoints |
Grant the narrowest set of scopes each key needs. A mobile app that only
transcribes should hold a stt:transcribe-only key.
Browser / WebSocket auth
Browsers cannot set the Authorization header on a WebSocket. For realtime
streams, mint a short-lived token from your server:
curl https://api.asas.flitc.tech/v1/auth/ws-token \
-H "Authorization: Bearer $ASAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "scopes": ["stt:transcribe"] }'The token is single-use, 60-second TTL, bound to (org, key, scopes) and passed
via Sec-WebSocket-Protocol — never in a query string (a log-leak vector).
Test mode
Use asas_test_… keys while integrating. They exercise the real models with small
quotas, mark every event livemode: false, and are excluded from billing rollups.
Flip to an asas_live_… key for production.
Rotation & revocation
- Create a new key, deploy it, then revoke the old one — zero downtime.
- Revocation is immediate across all gateway instances and tears down live streams using the revoked key.
- If a key leaks publicly (e.g. committed to GitHub), ASAS secret-scanning may
auto-revoke it and fire a
key.compromisedwebhook.