Authentication

The public API authenticates with two headers on every request: a workspace identifier and an API key. There is no OAuth flow, no bearer token and no session cookie. This is a server-to-server key pair.

The headers

string

required

Your Workspace ID. Accepts either form:

the workspace slug, for example acme-store (lowercase letters, digits and hyphens, up to 24 characters)
the workspace UUID, for example 9f1c2a44-4d0b-4f2e-9a6c-1b7d0e5a83c1

The value is trimmed and matched case-insensitively, and must be 64 characters or fewer. A slug is normalised before lookup, so surrounding whitespace and letter case do not matter.

string

required

A workspace API key. Keys are issued as sk_evt_ followed by 64 hexadecimal characters, for example sk_evt_4f2a9c7d1b0e63a58d4c2f9017be3a6d5c8f1e70a2b4d6c9e3f5a7b1c8d0e2f4.

Both headers are required on every call. They are matched case-insensitively, as HTTP header names always are.

Getting a key

A workspace can hold as many named keys as you need, so issue one per integration rather than sharing a single key. Only an owner or admin can create one.

Open the key screen

In the dashboard go to Settings and then API Tokens (/settings?section=api).

Create a key

Choose Create key and give it a name that identifies the integration, for example Production app or Make connector. The name is optional and defaults to API key; it can be up to 255 characters.

Copy it once

The full key is shown a single time, in the dialog that appears immediately after creation. Copy it into your secret store before closing that dialog.

Find your Workspace ID

Go to Settings and then Workspace. The Workspace ID field is the value to send as X-Sender-Tenant.

The full key is never retrievable again. After creation the key list shows only the first 16 characters as a prefix, the name, the creation date, the last-used timestamp and whether the key is active or revoked. If you lose a key, create a replacement and revoke the old one.

Managing keys over HTTP

These four routes are part of the dashboard API, not the public API. They authenticate with your dashboard session, not with an API key, so you cannot use one API key to mint another.

Method and path	Who can call it	Result
`GET /integrations/api-keys`	Any workspace member	Lists keys. Returns `id`, `name`, `keyPrefix`, `purpose`, `revoked`, `lastUsedAt` and `createdAt` for each. Never returns key material.
`POST /integrations/api-keys`	Owner, admin	Creates a key. The response adds `apiKey` with the full secret. This is the only time it is returned.
`DELETE /integrations/api-keys/:id`	Owner, admin	Revokes the key. Responds `204` with no body.
`DELETE /integrations/api-keys/:id/permanent`	Owner, admin	Permanently deletes a key that is already revoked. Responds `204` with no body.

POST /integrations/event-ingest-key also exists and creates an unnamed key. It predates the routes above and is kept for compatibility; prefer POST /integrations/api-keys. Errors on the management routes:

Status	Message	Cause
`400`	`Revoke the key before deleting it`	Permanent delete was called on a key that is still active. Revoke it first.
`404`	`API key not found`	No key with that id in this workspace.

What a key can do

A key is workspace-wide. There are no per-endpoint scopes and no read-only keys. One key authenticates every surface below, including writes. Keep keys server side, never ship one in client-side JavaScript or a mobile binary, and store them in a secret manager rather than in source control.

The same header pair authenticates all of these:

Surface	Endpoints
Public API	Everything under `/public`, including profile writes, list membership, transactional email and SMS, delivery status, webhook subscriptions and tag creation.
Event ingest	`POST /events/ingest`
OTP	`POST /otp/send`, `POST /otp/verify`
Embedded forms	`POST /forms/subscribe`
Web push	`POST /push/subscriptions`

Only POST /forms/subscribe is designed to be called from a browser; it is the one API-key endpoint that answers cross-origin requests. Every other endpoint listed above is server to server and will not be reachable from arbitrary web origins.

Example request

curl https://api.senderz.app/api/v1/public/me \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: $SENDERZ_API_KEY"

const res = await fetch("https://api.senderz.app/api/v1/public/me", {
  headers: {
    "X-Sender-Tenant": process.env.SENDERZ_WORKSPACE,
    "X-API-Key": process.env.SENDERZ_API_KEY,
  },
});

if (!res.ok) {
  const { message } = await res.json();
  throw new Error(`Senderz auth failed (${res.status}): ${message}`);
}

const { data } = await res.json();
console.log(data.tenant.name, data.apiVersion);

import os
import requests

res = requests.get(
    "https://api.senderz.app/api/v1/public/me",
    headers={
        "X-Sender-Tenant": os.environ["SENDERZ_WORKSPACE"],
        "X-API-Key": os.environ["SENDERZ_API_KEY"],
    },
    timeout=10,
)
res.raise_for_status()
data = res.json()["data"]
print(data["tenant"]["name"], data["apiVersion"])

Response:

{
  "success": true,
  "data": {
    "tenant": {
      "id": "9f1c2a44-4d0b-4f2e-9a6c-1b7d0e5a83c1",
      "slug": "acme-store",
      "name": "Acme Store",
      "plan": "c5000",
      "status": "active"
    },
    "apiVersion": "2026-01"
  }
}

Validate a connection

GET /public/me is the cheapest way to confirm a key works. It reads nothing but workspace metadata, so it is safe to call on startup or whenever a user pastes credentials into your integration. The Make connector uses this same endpoint to render its connection status.

Rotating a key

Rotation is a create-then-revoke sequence, so there is no window where your integration is offline.

Create the replacement

Settings and then API Tokens, then Create key. Both keys are valid at the same time.

Deploy the new key

Update your secret store and restart or redeploy anything holding the old key.

Confirm the old key is idle

The key list shows a Last used timestamp per key, stamped on every successful authentication. Wait until the old key stops advancing.

Revoke, then delete

Revoke the old key. Requests using it stop working immediately. Once revoked it can be permanently deleted; a key cannot be deleted while it is still active.

Add sk_evt_[0-9a-f]{64} to your secret-scanning rules so a leaked key is caught in code review and in commit hooks.

If a key leaks, revoke it first and create the replacement afterwards. Revocation takes effect on the next request.

Rate limits

Two independent limits are evaluated on every request, before the key is checked. A request can therefore be throttled without ever being authenticated.

Limit	Window	Keyed on	Applies to
60 requests	60 seconds	The caller source IP address	Every request that does not carry a signed dashboard session.
1,200 requests	60 seconds	The API key	Every request carrying `X-API-Key`. This is the default and can differ per deployment.

The 60-per-minute bucket is keyed on the source IP address, not on your key or your workspace. Everything calling from the same address shares it, including calls for other workspaces. Serialise your calls, batch where an endpoint supports it, and treat 60 per minute as the real ceiling for a single-host integration.

Two endpoints override the first bucket with their own limit:

Endpoint	Limit
`POST /forms/subscribe`	10 per minute
`POST /otp/send` and `POST /otp/verify`	60 per minute each

Rate limit headers

Any request that is not blocked carries the remaining budget. The per-key bucket uses the same header names with a -tenant suffix, so both buckets are visible at once.

Header	Meaning
`X-RateLimit-Limit`	Ceiling for the IP bucket in the current window.
`X-RateLimit-Remaining`	Requests left in the IP bucket.
`X-RateLimit-Reset`	Seconds until the IP bucket resets.
`X-RateLimit-Limit-tenant`	Ceiling for the per-key bucket.
`X-RateLimit-Remaining-tenant`	Requests left in the per-key bucket.
`X-RateLimit-Reset-tenant`	Seconds until the per-key bucket resets.

A throttled response

A blocked request returns 429 with a Retry-After header giving the number of seconds to wait. When it is the per-key bucket that blocked, the header is Retry-After-tenant instead.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 37
X-Request-Id: 8vQ2mKp4Rt9zLc1w

{
  "success": false,
  "message": "ThrottlerException: Too Many Requests"
}

Honour Retry-After rather than retrying on a fixed schedule, and back off exponentially if you keep hitting the limit.

Authentication errors

Both failures return 401 in the standard error envelope, with no code field.

boolean

Always false on an error.

string

A human-readable reason. Do not parse it; branch on the status code.

Status	Message	Cause
`401`	`Missing tenant or API key`	One or both headers were absent or empty.
`401`	`Invalid API key`	The key did not match an active key for the resolved workspace, or the key was revoked, or `X-Sender-Tenant` did not resolve to a workspace at all.

{
  "success": false,
  "message": "Invalid API key"
}

An unknown or malformed X-Sender-Tenant returns 401 Invalid API key, not a 404. The workspace is resolved before the key is compared, and a failed resolution is deliberately reported as an authentication failure so the endpoint cannot be used to probe which workspace slugs exist. When you get this error, check the workspace identifier as carefully as the key.

A 403 is never an authentication problem. It means the key authenticated but the action was refused, for example a transactional SMS with an insufficient credit balance. See Errors and rate limits for the full status-code table.

Debugging a 401

Check the workspace identifier first

Copy the Workspace ID from Settings and then Workspace rather than typing it. A workspace slug and a workspace name are not the same thing, and the slug is capped at 24 characters, so a long workspace name is not a valid identifier.

Check the key has not been revoked

Open Settings and then API Tokens. A revoked key still appears in the list with a Revoked status and will fail every request. The Last used column tells you whether the key you think you are sending is the one actually reaching the API.

Check the key survived transport

A key is sk_evt_ plus exactly 64 hex characters. Truncation, a trailing newline from a file read, or shell quoting that drops part of the value all produce the same Invalid API key. Compare the first 16 characters against the prefix shown in the key list.

Quote the request id when contacting support

Every response carries an X-Request-Id header. Capture it from the failing response and include it in a support request so the exact call can be traced.

Introduction

Ingest & transactional

Public API

The headers

Getting a key

Managing keys over HTTP

What a key can do

Example request

Validate a connection

Rotating a key

Rate limits

Rate limit headers

A throttled response

Authentication errors

Debugging a 401

​The headers

​Getting a key

​Managing keys over HTTP

​What a key can do

​Example request

​Validate a connection

​Rotating a key

​Rate limits

​Rate limit headers

​A throttled response

​Authentication errors

​Debugging a 401

The headers

Getting a key

Managing keys over HTTP

What a key can do

Example request

Validate a connection

Rotating a key

Rate limits

Rate limit headers

A throttled response

Authentication errors

Debugging a 401