Gravity SMS Docs

Apps

Register applications, manage settings, rotate API keys, and test webhook delivery.

POST/v1/apps/registeradmin

Register a new application and receive an API key.

Request body

NameTypeRequiredDescription
namestringRequiredApp display name, 1–100 characters.
tenantIdstringRequiredTenant to associate the app with. Required after bootstrap. Format: tenant_ + 16 hex characters.
webhookUrlstring | nullOptionalURL to receive inbound SMS webhooks. Must be HTTPS in production, max 2000 characters.
rolestringOptional"app" (default) or "admin". Only callers with an existing admin key can set this field. Admin keys have platform-wide access.
Request
curl -X POST https://smsgateway-api.onrender.com/v1/apps/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My CRM Integration",
    "tenantId": "tenant_abc123def456abcd",
    "webhookUrl": "https://my-app.example.com/webhooks/sms"
  }'

Success response

201 Created
json
{
  "appId": "app_f1e2d3c4b5a69870",
  "name": "My CRM Integration",
  "apiKey": "sgw_a1b2c3d4e5f6789012345678abcdef90",
  "apiKeyPrefix": "sgw_a1b2",
  "role": "app",
  "tenantId": "tenant_abc123def456abcd"
}
Store the API key immediately
The apiKey is returned once and cannot be retrieved again. The gateway stores only a SHA-256 hash.

Error responses

400 Invalid name
json
{
  "error": "name must be 1-100 characters"
}
400 Missing tenant
json
{
  "error": "tenantId is required when registering new apps"
}
400 Invalid tenant ID
json
{
  "error": "Invalid tenantId format"
}
400 Tenant not active
json
{
  "error": "Tenant not found or not active"
}
400 Invalid webhook URL
json
{
  "error": "Invalid webhookUrl: must be https:// in production, max 2000 chars"
}
403 Not admin
json
{
  "error": "Admin API key required to register new apps"
}
GET/v1/appsapp or admin

List all apps visible to the caller.

App role returns apps in the same tenant. Admin role returns all apps across all tenants. The apiKeyHash field is never returned.

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

Success response

200 OK
json
{
  "apps": [
    {
      "appId": "app_abc123def456abcd",
      "tenantId": "tenant_abc123def456abcd",
      "name": "My CRM Integration",
      "webhookUrl": "https://my-app.example.com/webhooks/sms",
      "role": "app",
      "isActive": true,
      "apiKeyPrefix": "sgw_a1b2",
      "lastUsedAt": "2026-03-01T09:30:00.000Z",
      "createdAt": "2026-02-15T12:00:00.000Z",
      "updatedAt": "2026-03-01T09:30:00.000Z"
    }
  ]
}
PUT/v1/apps/:appIdapp (own app) or admin

Update an app's webhook URL or active status.

Request body

NameTypeRequiredDescription
webhookUrlstring | nullOptionalNew webhook URL, or null to remove. Must be HTTPS in production, max 2000 characters.
isActivebooleanOptionalSet to false to deactivate the app (API key stops working).
Request
curl -X PUT https://smsgateway-api.onrender.com/v1/apps/app_abc123def456abcd \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://my-app.example.com/webhooks/sms"
  }'

Success response

200 OK
json
{
  "ok": true
}

Error responses

400 Invalid app ID
json
{
  "error": "Invalid appId format"
}
400 Invalid webhook URL
json
{
  "error": "Invalid webhookUrl: must be https:// in production, max 2000 chars"
}
404 Not found
json
{
  "error": "App not found"
}
DELETE/v1/apps/:appIdapp (own app) or admin

Deactivate an app (soft delete). The API key stops working immediately.

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

Success response

200 OK
json
{
  "ok": true
}

Error responses

400 Invalid app ID
json
{
  "error": "Invalid appId format"
}
404 Not found
json
{
  "error": "App not found"
}
POST/v1/apps/:appId/rotate-keyapp (own app) or admin

Generate a new API key, immediately invalidating the old one.

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

Success response

200 OK
json
{
  "apiKey": "sgw_new1a2b3c4d5e6f7a8b9c0d1e2f3a4b5",
  "apiKeyPrefix": "sgw_new1"
}
Old key invalidated immediately
The previous API key stops working as soon as this endpoint returns. Store the new key before discarding the response.

Error responses

400 Invalid app ID
json
{
  "error": "Invalid appId format"
}
404 Not found
json
{
  "error": "App not found"
}
POST/v1/apps/:appId/test-webhookapp (own app) or admin

Send a test payload to the app's configured webhook URL.

Sends a POST request with a test payload to the app's webhookUrl. The test payload has the following shape:

Test payload sent to your webhook
{
  "type": "test",
  "timestamp": "2026-03-01T12:00:00.000Z",
  "source": "smsgateway"
}
Request
curl -X POST https://smsgateway-api.onrender.com/v1/apps/app_abc123def456abcd/test-webhook \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response

If your webhook responds with a 2xx status:

200 OK
json
{
  "ok": true
}

If your webhook responds with a non-2xx status or times out (5 second timeout):

200 Webhook failed
json
{
  "ok": false,
  "status": 500,
  "error": "Internal Server Error"
}

Error responses

400 Invalid app ID
json
{
  "error": "Invalid appId format"
}
400 No webhook URL
json
{
  "error": "App has no webhookUrl configured"
}
404 Not found
json
{
  "error": "App not found"
}

Related docs