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 you create an app — either through the dashboard or 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
`app`	Account-scoped	Send/receive SMS, manage own app settings, check RC connection status. Each API key is scoped to a single app within your account.

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-keyapp (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.

WebSocket tokens

For WebSocket connections from browser environments, use ephemeral tokens instead of sending your API key to the client. Tokens are generated server-side and passed to the browser for authentication.

Request

curl -X POST https://smsgateway-api.onrender.com/v1/ws/token \
  -H "Authorization: Bearer YOUR_API_KEY"

200

json

{
  "token": "wst_a1b2c3d4...64 hex characters",
  "expiresIn": 60
}

Token format: wst_ prefix followed by 64 hexadecimal characters. Tokens are single-use (consumed on first WebSocket authentication), expire after 60 seconds, and are stored in-memory only.

Handshake only

WebSocket tokens are for the authentication handshake only. Once the connection is authenticated, the token is consumed and the connection persists independently — there is no need to refresh the token while connected. See the WebSocket API Reference for the full authentication flow.

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
WebSocket API — Token-based and API key authentication for real-time events