Skip to main content
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 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:write
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:all
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

ScopeDescription
accounts:readRead account information
accounts:writeUpdate account settings
accounts:billingAccess billing information
accounts:members:readView account members
accounts:members:addAdd new account members
accounts:members:updateUpdate member permissions
accounts:members:removeRemove account members

​
Domain Management

ScopeDescription
domains:readList and view domain information
domains:writeAdd 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

  • Global Scopes
  • Domain-Specific Scopes
ScopeDescription
messages:send:allSend messages from any domain
messages:cancel:allCancel messages from any domain
messages:read:allRead messages from any domain

​
Webhook Management

  • Global Scopes
  • Domain-Specific Scopes
ScopeDescription
webhooks:read:allRead webhooks for all domains
webhooks:write:allCreate/update webhooks for all domains
webhooks:delete:allDelete webhooks for all domains

​
Email Routing

  • Global Scopes
  • Domain-Specific Scopes
ScopeDescription
routes:read:allRead routes for all domains
routes:write:allCreate/update routes for all domains
routes:delete:allDelete routes for all domains

​
SMTP Credentials

  • Global Scopes
  • Domain-Specific Scopes
ScopeDescription
smtp-credentials:read:allRead SMTP credentials for all domains
smtp-credentials:write:allCreate/update SMTP credentials for all domains
smtp-credentials:delete:allDelete SMTP credentials for all domains

​
Suppressions

ScopeDescription
suppressions:readView suppression lists
suppressions:writeAdd suppressions
suppressions:deleteRemove specific suppressions
suppressions:wipeClear entire suppression list

​
API Key Management

ScopeDescription
api-keys:readList and view API keys
api-keys:writeCreate and update API keys
api-keys:deleteDelete API keys

​
Statistics and Reports

  • Global Scopes
  • Domain-Specific Scopes
ScopeDescription
statistics-transactional:read:allRead statistics for all domains

​
Scope Validation and Hierarchy

​
Validation Rules

  1. Domain Ownership: Domain-specific scopes are only valid if you own the specified domain
  2. No Duplicates: Duplicate scopes in the same API key are not allowed
  3. 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:all
4

Domain-Specific Check

For domain-specific operations, check if the API key has the exact domain scope and verify domain ownership.

​
Best Practices

Grant only the minimum scopes necessary for your application to function. This reduces security risks if an API key is compromised.
// Good: Specific scopes for a newsletter application
[
  "messages:send:{newsletter.com}",
  "suppressions:write",
  "statistics-transactional:read:{newsletter.com}"
]

// Avoid: Overly broad permissions
[
  "*"
]
Use domain-specific scopes when working with multi-tenant applications or when you want to restrict access to specific domains.
// For a multi-tenant SaaS app
[
  "messages:send:{client1.com}",
  "messages:read:{client1.com}",
  "webhooks:write:{client1.com}"
]
Create separate API keys for different applications or environments with appropriate scopes for each.
// Production key - minimal scopes
[
  "messages:send:all",
  "suppressions:write"
]

// Admin key - broader access
[
  "accounts:read",
  "api-keys:read",
  "domains:read"
]
Regularly review your API key scopes and remove any that are no longer needed. Update scopes when your application requirements change.