Skip to content
Waqar Wiki

Authenticate and choose scopes

Every API request uses a school-issued bearer credential. Browser cookies, passwords, and a school identifier are not API authentication.

Send the credential

Section titled “Send the credential”
GET /api/v1/school HTTP/1.1
Host: waqar.app
Authorization: Bearer <API_KEY>
Accept: application/json

Use TLS, send exactly one Authorization header, and keep the credential out of URLs and bodies. Start with GET /school; its data.id confirms the tenant attached to the key.

Read scopes

Section titled “Read scopes”
ScopePermitted resource
school:readAuthenticated school profile
semesters:readSemesters
halqas:readHalqas
sheikhs:readEligible sheikhs
students:readStudents
sessions:readSessions
attendance:readAttendance
recitations:readRecitations
learning_plans:readEnabled Learning Plans and assignments

students:sensitive:read is reserved and not assignable. Sensitive student fields are not exposed by v1. Surah reference operations require a valid API credential but no additional resource scope.

Write scopes

Section titled “Write scopes”
ScopePermitted resource
students:writeSupported student create/update operations
sessions:writeSupported session create/update/end operations
attendance:writeAttendance batch upsert
recitations:writeRecitation creation

A write scope on a key is necessary but not sufficient. The school must also have effective write capability, rollout eligibility, and an allowed current scope policy. Read eligibility never implies write eligibility.

Apply least privilege

Section titled “Apply least privilege”
  1. List the integration’s exact operations.
  2. Map each operation to the endpoint reference’s required scope.
  3. Create separate keys for unrelated systems and environments.
  4. Exclude future or “just in case” scopes.
  5. Replace the key if scopes need to change.
  6. Periodically remove unused keys and scopes through rotation.

Interpret authorization failures

Section titled “Interpret authorization failures”
  • 401 invalid_api_key: credential missing, malformed, unknown, expired, or revoked.
  • 403 insufficient_scope: the effective or key scope does not allow the operation; use error.details.required_scope for diagnosis.
  • Other 403 errors can reflect suspension, rollout, feature, network, or write-policy controls.

Never retry a 401 or 403 indefinitely. Correct the credential or obtain an authorized policy change. See endpoint reference.