API Keys

Create an API key

Mint a new API key on the project. The token is NOT returned — the response carries the key's 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.

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

Request

  • Base URL: https://api.sendly.now
  • URL: https://api.sendly.now/api/projects/{id}/api-keys
  • Auth: one of:
    • API key in cookie better-auth.session_token
    • OAuth 2 (authorization code, authorization URL https://app.sendly.now/api/auth/oauth2/authorize, token URL https://app.sendly.now/api/auth/oauth2/token, scopes: api-keys:write)

Path parameters

idstring required

Project id.

Request body

domainIdstring uuid nullable
legacyGrantPreset'FULL' | 'SENDING_ONLY'
mode'LIVE' | 'TEST'

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.

namestring required
scopesstring[]

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

Response

API key created; the secret is behind the reveal link.

successtrue required

Changes

No recorded changes to this operation across all 1 revision of this API.