Scoped API keys

Every API key gets
one clear job.

Choose exactly which capabilities, projects, and sender domains a workflow can use. A key can create another key only when it has api-keys:write, and never one broader than itself.

Create account Open API keys

Secret shown once
Immediate revocation
Server-side credentials

API keyProduction senderScoped

API keyntc_xxxxxxxxxxxxxxxxxxxxShown once

Sending onlyCustomFull access

Capabilityemail:sendSelected

ProjectAcme AppSelected

Sender domainnotify.acme.comSelected

Ready for server useRevoke instantly

Starts with ntc_Scopes never widenProject boundedDomain bounded

Three boundaries

Define what a key can do, and where.

Capabilities control the operation. Projects control the data boundary. Sender domains control which verified identities a sending workflow may use.

Capability groupScopes

MessagingSend and operate runtime channelsemail:send

WorkspaceProjects, credentials, and domainsprojects:readprojects:writeapi-keys:writedomains:readdomains:write

ContentTemplates and consent-based lifecycle mailtemplates:writeaudiences:writebroadcasts:writeautomations:write

OperationsEvents, recipient policy, and inbound emailwebhooks:writesuppressions:writereceiving:readreceiving:write

Canonical capability list

The public scope list comes from the product.

This page renders the same canonical capability array used by the API. Choose a full, sending-only, or custom preset; custom keys can combine any current scopes below with selected projects and domains.

Read the agent access guide

Scopes a key can carry

[
  "email:send",
  "sms:send",
  "sms:read",
  "sms:manage",
  "sms:billing:read",
  "projects:read",
  "projects:write",
  "api-keys:write",
  "domains:read",
  "domains:write",
  "templates:write",
  "audiences:write",
  "broadcasts:write",
  "automations:write",
  "webhooks:write",
  "suppressions:write",
  "receiving:read",
  "receiving:write"
]

Credential lifecycle

A narrow API key limits what rotation or revocation touches.

Separate credentials keep routine rotation or one revoked workflow from touching every integration in the workspace.

01GrantChoose the job
Start with full access, sending only, or a custom combination of capabilities, projects, and domains.
02BindSelect its resources
Keep a runtime inside one project or let a trusted operator work across a selected set.
03RunLet policy enforce it
Every API request checks the capability and resource boundary before the operation runs.
04RotateReplace, then revoke
Mint the replacement, update the workflow, and delete the old key without changing the account.

One key per workflow

Keep each credential’s scope small enough to explain.

Runtime, deploy, agent, and inbound jobs do not need the same authority. Give each one a credential whose purpose is obvious from its name and scope.

AppProduction sender

Dispatch transactional mail from the allowed project and sender domain, nothing more.

email:send

DeployTemplate publisher

Give CI its own credential for publishing template changes without a runtime send capability.

templates:write

AgentAuthorized operator

Size access to the agent’s task instead of handing it the keys to the whole workspace.

custom scopes

InboundReply processor

Read messages and attachments for the project that owns the receiving domain.

receiving:read

Delegation without escalation

A key can share less access, never more.

A key needs api-keys:write to list key metadata, create credentials, or revoke them. Any credential it creates must fit inside its own capabilities, projects, and domains.

Secrets appear only at creation
Revocation takes effect immediately
Permission failures stop at the boundary

See agent key rules

Delegated keyAllowed

PParent keyDeployment operatorBroader

api-keys:writetemplates:writeprojects: selected

may create

CChild keyTemplate publisherNarrower

templates:writeproject: Acme App

Privilege cannot expand.A child key must fit inside every capability and resource boundary carried by its parent.

Ready to scope it?

Give the next workflow exactly one job.

Create the key, copy its one-time secret into a server-only environment variable, and let the API enforce the boundary.