Authentication

Itqan APIs use an API key to identify your application. Public read endpoints currently work without one, but we recommend creating a key now — it unlocks account-aware features, higher rate limits, and keeps your integration ready as authentication rolls out more widely.

Get an API key

1. Sign in to the Asset Library at cms.itqan.dev.
2. Open your account settings and go to API Keys.
3. Create a key, give it a descriptive name (e.g. my-recitation-app), and copy it.

Store it securely. Treat the key like a password — keep it in an environment variable or secret manager, never commit it to source control or expose it in client-side code.

Send the key

Pass your key on every request in the X-API-Key header:

curl

curl https://staging.api.cms.itqan.dev/reciters/ \
  -H "X-API-Key: YOUR_API_KEY"

Python

import urllib.request
import json

req = urllib.request.Request(
    "https://staging.api.cms.itqan.dev/reciters/",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
with urllib.request.urlopen(req) as resp:
    data = json.load(resp)

print(f"Total reciters: {data['count']}")

JavaScript

const resp = await fetch("https://staging.api.cms.itqan.dev/reciters/", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { count, results } = await resp.json();

console.log(`Total reciters: ${count}`);

Identify end users

For per-end-user usage metrics, include an opaque, developer-chosen identifier in the X-External-User-Id header. Do not send names, email addresses, phone numbers, or other personally identifiable information. The value is treated as opaque metadata and is scoped to the application identified by your API key.

curl https://staging.api.cms.itqan.dev/reciters/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-External-User-Id: user-123"

The identifier may contain letters, numbers, ., _, :, and -, must start with a letter or number, and may be up to 64 characters long. Values that are empty, contain an email address, resemble a phone number, or use other invalid characters are rejected with a 422 response.

Errors

A missing or invalid key returns an error in the standard error format:

Status	Meaning	Fix
401 Unauthorized	Key is missing or malformed	Add a valid X-API-Key header
403 Forbidden	Key is valid but not allowed for this resource	Check the key's permissions in the Asset Library

Existing integrations against public read endpoints continue to work without disruption while the key requirement is phased in.

---

See also: Quickstart · Error Handling