Skip to content
PayloadPuffin.
Join the waitlist

API key scopes

To let your service send events without changing routing, give its API key only events:write. Scopes limit what a key can do. Each public API operation requires a scope. Reading and changing events, deliveries, destinations and sources each have their own scope. A key without the scope an operation needs gets 403 permission_denied.

Scopes and operations

ScopeConsole settingOperations
events:writeEvents: WriteSend an event, Rerun an unbuilt event
events:readEvents: ReadList events, Get an event
deliveries:writeDeliveries: WriteResend a delivery
deliveries:readDeliveries: ReadList deliveries, Get a delivery
destinations:writeDestinations: WriteCreate a destination, Delete a destination, Update a destination, Set destination delivery policy, Reset destination record settings, Reset destination delivery policy, Expire the previous signing secret, Set destination record settings, Rotate a destination signing secret, Create a transform, Rename a transform, Save a transform's draft, Preview a transform, Publish a transform, Delete a transform
destinations:readDestinations: ReadList destinations, Get a destination, List transforms, Get a transform
sources:writeSources: WriteCreate a source, Delete a source, Update a source, Set the GET URL check of a source, Remove the GET URL check of a source, Set the POST URL check of a source, Remove the POST URL check of a source, Expire the previous source signing secret, Expire the previous source token, Rotate a source token, Delete a source's signature verification, Set up signature verification for a source, Create a transform, Rename a transform, Save a transform's draft, Preview a transform, Publish a transform, Delete a transform, Upgrade a managed transform, Detach a managed transform
sources:readSources: ReadList sources, Get a source, List transforms, Get a transform
analytics:readAnalytics: AccessGet latency percentiles, Get an analytics series, Get analytics totals, Get usage

Rules

  • A key needs at least one scope. These nine are the only scopes a key can hold.
  • In the console, Write grants the write scope together with the read scope. Read grants the read scope alone. Access on Analytics grants analytics:read.
  • Get a destination with include=secret or include=previous_secret returns a signing secret. That request needs destinations:write as well as destinations:read.
  • Only API keys can call Send an event.
  • Owners and admins change a key's scopes in the console. The change can take up to a minute to take effect.

When a key is refused

StatusCodeWhen
401unauthenticatedThe key is missing, unknown, expired or deleted, or a revoked previous secret
403permission_deniedThe key lacks the operation's scope. The message names the scope, such as This API key requires the events:write scope.

Common sets

IntegrationScopes
Sends events onlyevents:write
Follows the quickstartevents:write, events:read, destinations:write, destinations:read
Monitors and resends failed deliveriesevents:read, deliveries:read, deliveries:write
Exports usage and delivery metricsanalytics:read