Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Getting Your API Key

1. Log in to the HMS Sovereign dashboard
2. Navigate to Settings > API Keys
3. Copy your API key

Making Authenticated Requests

Include your API key in the Authorization header with every request:

curl https://api.hmsovereign.com/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Request Headers

Example: Get Account Information

curl https://api.hmsovereign.com/api/v1/account \
  -H "Authorization: Bearer fl_live_abc123xyz..."

Response:

{
  "id": "user-uuid-here",
  "email": "you@example.com",
  "company_name": "Your Company",
  "minutes_balance": 500,
  "monthly_usage_minutes": 120,
  "active_numbers": 3,
  "active_agents": 2,
  "active_calls": 0
}

See Get Account Information for full details.

Rate Limits

The API enforces the following rate limits:

When you exceed a rate limit, the API returns a 429 Too Many Requests response.

Error Responses

401 Unauthorized

Returned when the API key is missing, invalid, or expired.

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Returned when your API key doesn't have permission for the requested resource.

{
  "error": "Forbidden",
  "message": "You don't have access to this resource"
}

Security Best Practices

1. Never expose your API key in client-side code - Always make API calls from your server
2. Rotate keys periodically - Generate new keys and revoke old ones regularly
3. Use environment variables - Store keys in environment variables, not in code
4. Monitor usage - Check your account dashboard for unexpected API activity