Authentication

The Gravity SMS API uses API keys for authentication. Every request to a protected endpoint must include a valid API key in the Authorization header.

API key format

API keys use the format sgw_ followed by 32 hexadecimal characters. Example:

text

sgw_a1b2c3d4e5f6789012345678abcdef90

API keys are generated when an app is registered via POST /v1/apps/register. The full key is returned exactly once — the gateway stores only a SHA-256 hash. Store the key securely; it cannot be retrieved after creation.

Using the API key

Include the key as a Bearer token in the Authorization header:

bash

curl https://smsgateway-api.onrender.com/v1/rc/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Roles

Each API key is assigned a role that determines what endpoints the key can access.

Role	Scope	Access
`admin`	Platform-wide	All endpoints. Can manage tenants, view all messages, create apps for any tenant.
`app`	Tenant-scoped	Send/receive SMS, manage own app settings, check RC connection status. Cannot access other tenants or admin endpoints.

Key rotation

Rotate an API key to invalidate the current key and generate a new one. The old key stops working immediately.

POST/v1/apps/:appId/rotate-keyadmin or app (own app)

Request

curl -X POST https://smsgateway-api.onrender.com/v1/apps/app_abc123def456abcd/rotate-key \
  -H "Authorization: Bearer YOUR_API_KEY"

200

json

{
  "apiKey": "sgw_new1a2b3c4d5e6f7a8b9c0d1e2f3a4b5",
  "apiKeyPrefix": "sgw_new1"
}

Store the new key immediately

The new API key is returned once. The old key is invalidated immediately. Update your application configuration before the response is discarded.

Key prefix

The apiKeyPrefix field (e.g. sgw_6f45) is stored alongside the key hash and returned in app listings. Use it to identify which key is in use without exposing the full key.

Usage tracking

The gateway tracks the last time each API key was used via the lastUsedAt field on the app record. This value is updated at most once per minute per key.

Error responses

Authentication failures return the following responses:

No Authorization header, or header format is not Bearer <key>:

401 Missing or invalid API key

json

{
  "error": "Missing or invalid API key"
}

Header is present and correctly formatted, but the key does not match any active app:

401 Invalid API key

json

{
  "error": "Invalid API key"
}

403 Tenant suspended or inactive

json

{
  "error": "Tenant suspended or inactive"
}

429 Too many failed attempts

json

{
  "error": "Too many requests"
}

After 10 failed authentication attempts from the same IP within 5 minutes, the IP is blocked for 15 minutes. The 429 response includes a Retry-After header with the remaining block duration in seconds.

Related docs

Apps API Reference — Register apps and manage API keys
Security — Key hashing, HTTPS enforcement, and other security measures
Rate Limits — Per-key rate limits and failed auth blocking