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
| Scope | Console setting | Operations |
|---|
events:write | Events: Write | Send an event, Rerun an unbuilt event |
events:read | Events: Read | List events, Get an event |
deliveries:write | Deliveries: Write | Resend a delivery |
deliveries:read | Deliveries: Read | List deliveries, Get a delivery |
destinations:write | Destinations: Write | Create 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:read | Destinations: Read | List destinations, Get a destination, List transforms, Get a transform |
sources:write | Sources: Write | Create 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:read | Sources: Read | List sources, Get a source, List transforms, Get a transform |
analytics:read | Analytics: Access | Get 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
| Status | Code | When |
|---|
401 | unauthenticated | The key is missing, unknown, expired or deleted, or a revoked previous secret |
403 | permission_denied | The key lacks the operation's scope. The message names the scope, such as This API key requires the events:write scope. |
Common sets
| Integration | Scopes |
|---|
| Sends events only | events:write |
| Follows the quickstart | events:write, events:read, destinations:write, destinations:read |
| Monitors and resends failed deliveries | events:read, deliveries:read, deliveries:write |
| Exports usage and delivery metrics | analytics:read |