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.