Documentation / Authentication

Authentication

All API requests must be authenticated using an API key. Learn how to generate keys, format headers, and understand permission tiers.

API Keys

API keys are generated from your dashboard and are tied to your organization. Each key has a specific permission tier that determines which endpoints you can access.

Key Format

API keys follow this format:

pk_pub_ - Public tier
pk_paid_ - Paid tier
pk_ent_ - Enterprise tier

Header Format

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

Example Request

curl https://api.souratlas.io/api/devices \
  -H "Authorization: Bearer pk_pub_1234567890abcdef" \
  -H "Content-Type: application/json"

Permission Tiers

Different endpoints require different permission tiers. Higher tiers have access to all lower tier endpoints.

Tier	Access	Endpoints
Public	Device registry, basic metadata	/api/devices, /api/variants
Paid	Pricing intelligence, repair data	/api/pricing, /api/repairs
Enterprise	IMEI/serial risk assessment	/api/imei

Best Practices

Never expose API keys in client-side code or public repositories
Use environment variables to store API keys
Rotate keys regularly (recommended every 90 days)
Use separate keys for development and production environments
Monitor API key usage in your dashboard
Revoke compromised keys immediately

Authentication Errors

401 Unauthorized

Missing or invalid API key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Please provide a valid API key."
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

403 Forbidden

Insufficient permissions for endpoint

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "This endpoint requires enterprise tier access. Please upgrade your plan."
  },
  "timestamp": "2024-01-15T10:30:00Z"
}