API key scopes
Every scope your key can request, what each allows, and which endpoints require it.
Loading article…
API keys use scopes to limit what an integration can do. When you create a key, select only the scopes your app needs.
Every /api/v1 request also counts toward your team's monthly API request quota when billing is enabled. Failed requests (non-2xx) are refunded.
| Scope | Allows |
|---|---|
account:read | Read team profile (GET /api/v1/team) |
account:update | Update team profile (PATCH /api/v1/team) |
| Scope | Allows |
|---|---|
members:read | List members and pending invites |
members:create | Invite new members |
members:update | Change member roles |
members:delete | Remove members or cancel invites |
| Scope | Allows |
|---|---|
notifications:read | List channels, rules, and events |
notifications:create | Create channels and rules |
notifications:update | Update channels and rules |
notifications:delete | Delete channels and rules |
EmailGuard's product API scope. Requires the Public API module.
| Scope | Allows |
|---|---|
email:detect | Analyze an email address (GET /api/v1/emails/detect?email=...) |
The detect endpoint returns syntax validation, normalized form, subaddressing, and boolean flags for role addresses, public domains, relay providers, and disposable domains. See Detect email characteristics for the full response schema, and Email detection overview for a guide to each signal.
Signup and CRM integrations usually need only email:detect on a dedicated key. Do not grant team-management or notification scopes unless that same key must call those endpoints too.
Detect requests share your team's monthly API quota when billing is enabled. Rate limit: 60 requests per minute per API key (separate bucket from other /api/v1 routes). See API rate limiting.
When your fork registers custom routes under /api/v1/tools/*:
| Scope | Allows |
|---|---|
tools:read | Poll job results and other read-only tool endpoints |
tools:write | Start async tool jobs (POST /api/v1/tools/*) |
Most tool integrations need both scopes: POST returns a job_id, then GET poll endpoints require tools:read.
Polling tool results allows a higher per-minute limit (300/min) than starting jobs (60/min). See API rate limiting for response headers and RFC references.
Each endpoint in the API reference lists its required scope. Requests without the right scope return 403 Forbidden.
Team roles (Owner, Admin, Member, Billing) control who can manage keys in the dashboard — not what a key can do once created. See Team roles and permissions.
Successful /api/v1 calls are also listed in the team audit log as API REQUEST events. See audit log events for a field-by-field reference.