Limit API keys to specific capabilities for better security and access control. Scoped keys can only invoke the capabilities you explicitly allow.
Why scope API keys
Scoping provides security and organizational benefits:
- Least privilege — Give third parties access to only what they need
- Reduce attack surface — Compromised keys can’t access all capabilities
- Usage tracking — See which keys are calling which capabilities
- Billing isolation — Track costs per integration or customer
Creating a scoped key
- Open your API surface
- Find API Keys
- Click Create API Key
- Enter a name (e.g., “Mobile app - FAQ only”)
- Under Scope, select Specific capabilities
- Check the capabilities this key should access
- Click Create
- Copy the key immediately
Access denied errors
When a key tries to access a capability it’s not scoped to:
HTTP status: 403 Forbidden
Updating scope
Modify a key’s scope after creation:
- Find the key in your API surface settings
- Click Edit
- Change capability selections
- Click Save
Changes take effect immediately. Existing requests with the key will use the new scope.
Use cases
Customer-specific keys
Create a key for each customer, scoped to capabilities relevant to them:
- Customer A: FAQ + Order lookup capabilities
- Customer B: FAQ capability only
Integration separation
Isolate different integrations:
- Mobile app key: All capabilities
- Public API key: Safe, rate-limited capabilities only
- Internal tools key: Admin and diagnostic capabilities
Third-party developers
Give partners access to specific features without exposing your entire Product.
Name keys descriptively with their scope (e.g., “Acme Corp - FAQ only” instead of “API Key 3”). This makes management easier as you scale.
Unscoped keys
Keys can also be unscoped, granting access to all capabilities on the Product. This is convenient for trusted integrations but increases risk if the key is compromised.
Use unscoped keys only when necessary and rotate them regularly.
Next steps
