Authentication
Authenticate every request with a Madeenan API key. Keep Madeenan keys, admin tokens, and any model provider keys inside your own backend.
What This Does
API keys identify your app, enforce scopes, and apply rate limits. Admin tokens create apps and issue keys.
Minimal Request
$curl "https://api.madeenan.com/v1/search?q=Ayat%20al-Kursi&limit_per_source=3" \
-H "X-Madeenan-API-Key: mdeen_live_..."
Headers
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| X-Madeenan-API-Key | string | Yes | — | Authenticates Search, Chat, feedback, and session requests. |
| X-Admin-Token | string | Yes | — | Authenticates app creation, API key issuance, usage, and indexing endpoints. |
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| search | scope | No | — | Allows search and direct Qur'an/Hadith lookup endpoints. |
| chat | scope | No | — | Allows chat, sessions, and feedback workflows. |
Admin Example
$curl https://api.madeenan.com/v1/admin/apps \
-H "X-Admin-Token: local-admin-token" \
-H "Content-Type: application/json" \
-d '{
"name": "Production App",
"slug": "production-app",
"allowed_origins": ["https://app.example.com"]
}'
Common Mistakes
- Using an admin token for public app traffic.
- Shipping a Madeenan API key in a browser bundle.
- Calling chat with a key that only has the search scope.
- Forgetting to register browser origins for client-side prototypes.
Security note
Treat Madeenan API keys like backend credentials. Treat admin tokens like root credentials.