API Keys | senderZ Docs

API keys are the primary way to authenticate with the senderZ API. Each key is scoped to a single tenant and carries its own rate limit. You can create multiple keys to separate production, staging, and development traffic.

Key Format

senderZ API keys use a prefix system so you can identify their purpose at a glance:

Prefix	Environment	Behavior
`sz_live_`	Production	Messages are delivered to real phones
`sz_test_`	Test / Sandbox	Messages are validated but never sent

Both prefixes work identically for authentication. The difference is that test keys skip the final delivery step, making them safe for development and CI pipelines.

Create an API Key

POST /v1/api-keys

Generate a new API key for your tenant.

Parameters

name string Required

A human-readable label for this key (e.g. “Production Server”, “CI Pipeline”).

rate_limit number

Maximum API calls per minute for this key. Defaults to your plan limit if omitted. Starter: 50 rpm, Growth: 200 rpm, Scale: unlimited.

Example Request

curl -X POST https://api.senderz.com/v1/api-keys \
  -H "Authorization: Bearer sz_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Server"}'

201 Created

{
  "data": {
    "id": "01JKEY123ABC",
    "name": "Production Server",
    "key": "sz_live_a1b2c3d4e5f6...",
    "rate_limit": 200,
    "created_at": "2026-04-15T10:30:00Z"
  }
}

List API Keys

GET /v1/api-keys

List all API keys for your tenant.

Returns all active keys. The actual key value is never returned — only the last four characters are shown for identification.

Example Request

curl https://api.senderz.com/v1/api-keys \
  -H "Authorization: Bearer sz_live_YOUR_KEY"

200 OK

{
  "data": [
    {
      "id": "01JKEY123ABC",
      "name": "Production Server",
      "key_hint": "...f6g7",
      "rate_limit": 200,
      "last_used_at": "2026-04-15T09:22:00Z",
      "created_at": "2026-04-15T10:30:00Z"
    },
    {
      "id": "01JKEY456DEF",
      "name": "Staging",
      "key_hint": "...h8i9",
      "rate_limit": 50,
      "last_used_at": null,
      "created_at": "2026-04-14T08:00:00Z"
    }
  ]
}

Delete an API Key

DELETE /v1/api-keys/:id

Revoke an API key permanently.

Revoking a key is immediate and irreversible. Any request using the revoked key will receive a 401 INVALID_API_KEY error.

id string Required

The ULID of the API key to revoke, returned when the key was created or listed.

Example Request

curl -X DELETE https://api.senderz.com/v1/api-keys/01JKEY123ABC \
  -H "Authorization: Bearer sz_live_YOUR_KEY"

200 OK

{
  "data": {
    "id": "01JKEY123ABC",
    "revoked": true
  }
}

Rate Limits by Plan

Each API key inherits a default rate limit based on your subscription plan. You can set a lower custom limit when creating a key, but you cannot exceed your plan ceiling.

Plan	Default Rate Limit	Monthly API Calls
Trial (14-day)	50 rpm	50,000
Starter ($49/mo)	50 rpm	50,000
Growth ($249/mo)	200 rpm	200,000
Scale ($749/mo)	Unlimited	Unlimited

When a key hits its rate limit, the API returns 429 RATE_LIMIT_EXCEEDED with a Retry-After header indicating how many seconds to wait.

Best Practices

Use test keys for development. Keys prefixed with sz_test_ validate your requests without sending real messages or consuming quota.
One key per environment. Create separate keys for production, staging, and CI so you can revoke one without affecting others.
Store keys in environment variables. Never commit keys to version control. Use SENDERZ_API_KEY as the standard variable name.
Rotate keys periodically. Create a new key, update your environment, verify it works, then revoke the old one.
Monitor usage. Check last_used_at on the list endpoint to identify stale keys that should be revoked.