Skip to Content
SendlySendly
API ReferenceApi keys

Create an API key

POST
/api/projects/{id}/api-keys

Mint a new API key on the project. What comes back depends on who is calling. A signed-in dashboard session receives the key's metadata and the token itself in plaintextToken, once. Any other caller (an OAuth token, so an agent or MCP tool) does not receive the token: the response carries the metadata plus a one-time revealUrl that only a signed-in dashboard session can open.

Scope attenuation: a key created with a delegated credential (an OAuth token or another API key) may not carry a scope that credential does not itself hold. A request that asks for more is refused with 400 SCOPE_ESCALATION rather than quietly narrowed, so the mistake is reported where it was made instead of surfacing later as an unexplained 403. Naming only legacyGrantPreset counts as asking for every scope that preset implies.

Requires the api-keys:write scope — Create, rotate, and revoke API keys — these keep working even after you disconnect this app.

cookiebetter-auth.session_token<token>

BetterAuth session cookie. Used by the dashboard / browser clients. When present, the active project is taken from the x-project-id header.

id*string

Project id.

application/json
  1. body
name*string
Length1 <= length <= 120
legacyGrantPreset?string
Value in"FULL""SENDING_ONLY"
mode?string

LIVE (default) or TEST. A test key can only send from the project's sandbox address, which accepts only the project's own verified account addresses as recipients, so it cannot reach a customer. Its sends are real sends down the same pipeline and are marked sentInTestMode. Fixed at creation.

Value in"LIVE""TEST"
scopes?array<>

The explicit grant the new key will carry. Omitted ⇒ materialised from legacyGrantPreset. A SENDING_ONLY key may carry only emails:send.

tiers?array<>

Permission groups: the key carries every scope of each named tier. Send tiers or scopes, not both (422).

Items1 <= items
domainId?|
Formatuuid

Response Body

API key created. The secret is in plaintextToken for a dashboard session, behind revealUrl for everyone else.

application/json
  1. response
success*true
Value intrue
data*

An API key's metadata. Never carries the token or its hash — lastFour is the only surviving fragment of the secret once the key has been created.

Example Request
curl -X POST 'https://api.sendly.now/api/projects/string/api-keys' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
Example Response
{  "success": true,  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",    "name": "string",    "lastFour": "string",    "legacyGrantPreset": "FULL",    "mode": "LIVE",    "scopes": [      "emails:send"    ],    "domainId": "8a0b02c3-fdd8-452e-bc6e-ef07a335ec7e",    "lastUsedAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "revokedAt": "2019-08-24T14:15:22Z",    "plaintextToken": "string",    "revealUrl": "http://example.com",    "revealExpiresAt": "2019-08-24T14:15:22Z"  }}