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 And Scopes
| 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 | — | Grants access to search and direct Qur'an/Hadith lookups. |
| chat | scope | No | — | Grants access to chat, sessions, and feedback. |
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.