Gravity SMS Docs

Apps

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

POST/v1/apps/registerapp

Register a new application and receive an API key. You can also create apps from the dashboard.

Request body

NameTypeRequiredDescription
namestringRequiredApp display name, 1–100 characters.
tenantIdstringRequiredTenant to associate the app with. Format: tenant_ + 16 hex characters.
webhookUrlstring | nullOptionalURL to receive inbound SMS webhooks. Must be HTTPS in production, max 2000 characters.
rolestringOptional"app" (default). Each app key is scoped to your account.
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",
  "webhookSecret": "whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "role": "app",
  "tenantId": "tenant_abc123def456abcd"
}
Store the API key and webhook secret immediately
The apiKey and webhookSecret are returned once and cannot be retrieved again. The gateway stores only hashed/encrypted versions. Use the webhook secret to verify webhook signatures.

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"
}
GET/v1/appsapp

List all apps in your account.

Returns all apps in your account. 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)

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)

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)

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/rotate-webhook-secretapp (own app)

Generate a new webhook secret, immediately invalidating the old one.

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

Success response

200 OK
json
{
  "webhookSecret": "whsec_new1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1"
}
Old secret invalidated immediately
The previous webhook secret stops working as soon as this endpoint returns. Update your verification logic with the new secret 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)

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