Overview
API Key Scopes
Understand how API key scopes control access to resources and operations in AhaSend
API Key Scopes
API key scopes define the permissions and access levels for your API keys. They control which operations your API key can perform and which resources it can access. AhaSend uses a granular scoping system that allows you to grant only the minimum necessary permissions for enhanced security.Types of Scopes
AhaSend supports three types of scopes:Static Scopes
Static Scopes
Static scopes provide fixed permissions that don’t change based on context. These are used for account-level operations and general resource access.Example:
accounts:read, domains:writeGlobal Scopes
Global Scopes
Global scopes end with
:all and provide access to all resources of a specific type across all domains in your account.Example: messages:send:all, webhooks:read:allDomain-Specific Scopes
Domain-Specific Scopes
Domain-specific scopes are restricted to a particular domain. They use curly braces to specify the domain name placeholder.Example:
messages:send:{example.com}, routes:write:{mydomain.com}The wildcard scope
* grants all permissions and should be used with extreme caution, preferably only for development and testing.Available Scopes
Account Management
| Scope | Description |
|---|---|
accounts:read | Read account information |
accounts:write | Update account settings |
accounts:billing | Access billing information |
accounts:members:read | View account members |
accounts:members:add | Add new account members |
accounts:members:update | Update member permissions |
accounts:members:remove | Remove account members |
Domain Management
| Scope | Description |
|---|---|
domains:read | List and view domain information |
domains:write | Add and update domains |
domains:delete:{domain} | Delete a specific domain |
Domain deletion requires a domain-specific scope for security. You cannot use a global scope for domain deletion.
Message Operations
| Scope | Description |
|---|---|
messages:send:all | Send messages from any domain |
messages:cancel:all | Cancel messages from any domain |
messages:read:all | Read messages from any domain |
Webhook Management
| Scope | Description |
|---|---|
webhooks:read:all | Read webhooks for all domains |
webhooks:write:all | Create/update webhooks for all domains |
webhooks:delete:all | Delete webhooks for all domains |
Email Routing
| Scope | Description |
|---|---|
routes:read:all | Read routes for all domains |
routes:write:all | Create/update routes for all domains |
routes:delete:all | Delete routes for all domains |
SMTP Credentials
| Scope | Description |
|---|---|
smtp-credentials:read:all | Read SMTP credentials for all domains |
smtp-credentials:write:all | Create/update SMTP credentials for all domains |
smtp-credentials:delete:all | Delete SMTP credentials for all domains |
Suppressions
| Scope | Description |
|---|---|
suppressions:read | View suppression lists |
suppressions:write | Add suppressions |
suppressions:delete | Remove specific suppressions |
suppressions:wipe | Clear entire suppression list |
API Key Management
| Scope | Description |
|---|---|
api-keys:read | List and view API keys |
api-keys:write | Create and update API keys |
api-keys:delete | Delete API keys |
Statistics and Reports
| Scope | Description |
|---|---|
statistics-transactional:read:all | Read statistics for all domains |
Scope Validation and Hierarchy
Validation Rules
- Domain Ownership: Domain-specific scopes are only valid if you own the specified domain
- No Duplicates: Duplicate scopes in the same API key are not allowed
- Redundancy Filtering: Specific domain scopes are automatically removed if a global scope exists
If you have both
messages:send:all and messages:send:{example.com}, only the global scope will be retained as it already covers the specific domain scope.Scope Hierarchy
Authorization Flow
When an API request is made, the system checks scopes in the following order:1
Wildcard Check
If the API key has the
* scope, access is granted immediately.2
Exact Match
Check if the required scope exactly matches any of the API key’s scopes.
3
Global Scope Check
For dynamic scopes, check if a corresponding
:all scope exists.Example: messages:send:{example.com} is satisfied by messages:send:all4
Domain-Specific Check
For domain-specific operations, check if the API key has the exact domain scope and verify domain ownership.
Best Practices
Principle of Least Privilege
Principle of Least Privilege
Grant only the minimum scopes necessary for your application to function. This reduces security risks if an API key is compromised.
Domain-Specific Scopes
Domain-Specific Scopes
Use domain-specific scopes when working with multi-tenant applications or when you want to restrict access to specific domains.
Separate API Keys
Separate API Keys
Create separate API keys for different applications or environments with appropriate scopes for each.
Regular Scope Audits
Regular Scope Audits
Regularly review your API key scopes and remove any that are no longer needed. Update scopes when your application requirements change.