API Access Documentation

Live API Tester

Test your API key with a real request against the production API host (https://api.sarafa.pk) and inspect status, rate-limit headers, and response payload.

curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities/karachi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

Access Rules

• Only authenticated users can create API keys.
• API keys are valid only for city-wise gold/silver rate endpoints (single-city and multi-city).
• Every request must include X-API-Key header and use the production API host https://api.sarafa.pk.
• For web clients, configure allowed website origins and keep web platform enabled.
• For mobile/server clients, use X-Client-Platform: mobile or server.
• For multi-city calls, pass comma-separated city slugs in slugs query param (maximum 50).
• Daily quota is enforced per key (429 on exceed).
• Raw key is shown only once during creation.

Endpoint Catalog

Production API Base URL: https://api.sarafa.pk

Rate Limit Headers

• X-RateLimit-Limit-Day - Daily quota
• X-RateLimit-Remaining-Day - Remaining requests today
• X-RateLimit-Reset - Reset timestamp

Platform & Origin Headers

• X-Client-Platform: server | mobile | web
• Web requests are validated against allowed origins using the Origin header.
• Mobile and server requests should set X-Client-Platform and usually do not send Origin.

cURL Examples

# 1) Login (Get JWT)
curl -X POST "https://api.sarafa.pk/api/v1/auth/v2/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=03001234567&password=YourPassword"

# 2) Create API key
curl -X POST "https://api.sarafa.pk/api/v1/api-keys/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Backend Server Key"}'

# 3) Call city gold rate
curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities/karachi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

# 4) Call city silver rate
curl -X GET "https://api.sarafa.pk/api/v1/public-rates/silver/cities/lahore" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

# 5) Call multi-city gold rates
curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities?slugs=karachi,lahore,islamabad" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: mobile"

# 6) Call multi-city silver rates
curl -X GET "https://api.sarafa.pk/api/v1/public-rates/silver/cities?slugs=karachi,lahore,islamabad" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: mobile"

# 7) Web origin-restricted request
curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities/karachi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://app.example.com"

Error Contract

{ "detail": "message" }

Testing Checklist (Production QA)

1. API key creation succeeds after JWT login.
2. Raw key appears only in create response, never in list endpoint.
3. Origin allowlist is enforced for web requests.
4. Platform restrictions block disallowed client types.
5. Gold/silver city endpoints return 200 with valid key.
6. Multi-city endpoints return correct requested_count, count, data, and not_found.
7. Missing/invalid key returns 401.
8. Revoked key returns 403.
9. 429 is returned when daily quota is exceeded with reset header.
10. Usage endpoint reports accurate today hits and remaining quota.
11. No quota bypass under high concurrency.