Authentication

All client endpoints require an API key passed via the X-API-Key header.

curl https://api.ugrat.com/api/v1/messages \
  -H "X-API-Key: uk_live_a3f9c2e1..."

Keys are created in the client portal and always start with uk_live_. The full key is shown once, at creation — store it securely; only its prefix is visible afterwards. A key can be deactivated or deleted from the portal at any time.

Requests without a valid key return 401 UNAUTHORIZED. A key belonging to an account that is still awaiting approval returns 403 ACCOUNT_PENDING; a blocked account returns 403 ACCOUNT_BLOCKED.

Rate limits

Requests are rate-limited per account. Sending endpoints (/api/v1/otp/send, POST /api/v1/messages) have their own, tighter budget because every accepted request dispatches a real SMS. Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). When the limit is exceeded you receive 429 RATE_LIMITED with a Retry-After header.

If the rate limiter is briefly unavailable, sending endpoints answer 503 SERVICE_UNAVAILABLE with Retry-After instead of letting requests through; wait the indicated number of seconds and retry.