Scoped API Keys and SMTP Credentials

Limit AhaSend SMTP credentials and API keys to specific sending domains, and give API v2 keys only the permission scopes each integration needs.

AhaSend scoped credentials restrict API keys and SMTP logins to the domains and operations they need; this guide helps you choose the right credential.

Available on Free, Pro and Max. See plans and features.

Enhanced Security: Scoped credentials reduce attack surface by limiting potential damage if a credential is compromised.

Types of Scoped Credentials

AhaSend provides two distinct credential types with different scoping capabilities:

Sending Credentials

SMTP & API v1/v2 sending keys

Domain-scoped credentials for email sending operations only

API v2 Keys

Full API access keys

Advanced scoping with both domain restrictions and operation permissions

---

Sending Credentials (Domain Scoping)

Sending credentials are created from the Credentials tab and are designed specifically for email sending operations. These include SMTP credentials, API v1 keys, and API v2 sending keys.

Global vs. Scoped Sending Credentials

Global Credentials (Default):

• Access: Can send from any verified domain in your account
• Use case: General-purpose credentials for multi-domain applications
• Risk: Higher impact if compromised

Domain-Scoped Credentials:

• Access: Limited to specific domains you select
• Use case: Application-specific credentials or domain isolation
• Risk: Limited damage potential if compromised

Principle of Least Privilege: Always scope credentials to the minimum domains required for your use case.

Create a Sending Credential

Follow send-only API key setup or SMTP credential setup, and choose only the sending domains your application needs.

API v2 Keys (Advanced Scoping)

API v2 keys are created from Account Settings → API Keys and provide full access to the AhaSend API v2 with granular permission and domain scoping.

Restrict by IP as well: API v2 keys can also be limited to a set of IP addresses. See IP Allow Lists.

Advanced Scoping Capabilities

API v2 keys support both domain restrictions and operation-level permissions:

Domain Scoping:

• Restrict API operations to specific domains
• Control which domains the key can manage or send from

Permission Scoping:

• Granular control over API operations (read, write, delete)
• Resource-specific access (messages, domains, webhooks, statistics)
• Explicit scopes for each allowed action

Create a Full API Key

Follow API authentication for the creation steps and scopes for the permission names. Give the key only the operations it needs.

How Sending Credential Scoping Works

When you use a domain-scoped sending credential, AhaSend validates the sending domain:

SMTP Credentials:

• Validates: MAIL FROM address domain
• Checks: Domain is in the credential’s authorized list
• Action: Refuses connection if unauthorized

API v1/v2 Sending:

• Validates: from.email domain in request payload
• Checks: Domain scope against the API key
• Action: Rejects request if domain is not authorized

Sending Credential Error Messages

When using credentials outside their domain scope:

SMTP Authentication Error

SMTP Connection Rejected:

authz_id 'YOUR_USERNAME' is not authorized to send as tenant 'YOUR_ACCOUNT_ID' or from this domain

API v1 Error

API v1 Request Error:

{
  "status": "API Key is not scoped for this domain"
}

API v2 Sending Error

API v2 Request Error:

{
  "message": "this api key is not authorized to send messages from the domain 'example.com'"
}

API v2 Key Validation

API v2 keys undergo comprehensive validation for each request:

Permission Validation:

• Operation Check: Verifies the key has permission for the requested operation
• Resource Access: Ensures access to specific resources (domains, webhooks, etc.)
• Hierarchy Enforcement: Respects scope hierarchy and inheritance rules

Domain Validation:

• Resource Domain: Checks if the key can access resources for the specified domain
• Sending Domain: Validates sending permissions for message operations

API v2 Key Error Messages

When using API v2 keys outside their defined scope:

Permission Scope Errors

Insufficient Permissions:

{"message": "Insufficient permissions"}

Resource Access Denied:

{"message": "Access denied"}

Domain Scope Errors

Domain Not Authorized:

{
  "message": "this api key is not authorized to send messages from the domain 'example.com'"
}

Advanced Permission Scoping

For granular control over API operations, API v2 keys support detailed permission scopes:

Common Scope Categories

• Account Management: accounts:read, accounts:write
• Message Operations: messages:send:all, messages:read:{domain}
• Domain Management: domains:read, domains:write
• Webhook Control: webhooks:write:all, webhooks:delete:{domain}
• Statistics Access: statistics-transactional:read:all

Scope Types

• Static Scopes: Fixed permissions like accounts:read
• Global Scopes: Domain-wide access with :all suffix
• Domain-Specific: Restricted to particular domains using {domain} syntax

Detailed Documentation: For complete scope definitions, validation rules, and examples, see our API Scopes Reference.

Benefits and Best Practices

Scoped credentials provide significant advantages regardless of type:

Security Benefits

Enhanced Security

Minimize compromise impact:

• Limit potential damage from stolen credentials
• Reduce attack surface with principle of least privilege
• Prevent unauthorized access to sensitive domains

Improved Control

Granular access management:

• Separate credentials for different applications
• Team-specific permissions and domain access
• Environment-specific scoping (staging vs. production)

Error Prevention

Prevent configuration mistakes:

• Block accidental sending from wrong domains
• Catch misconfigurations early in development
• Protect production domains from test applications

Easier Management

Simplified credential administration:

• Clear understanding of credential capabilities
• Easy revocation of specific domain access
• Organized credential structure for complex setups

Implementation Best Practices

Credential Strategy

Design your scoping approach:

• Application-specific keys: One key per application or service
• Environment separation: Different keys for staging, production
• Domain isolation: Separate keys for different business domains
• Minimal permissions: Grant only necessary scopes

Security Management

Maintain credential security:

• Regular audit of active credentials and their scopes
• Rotate credentials periodically
• Remove unused or outdated credentials
• Monitor for scope violation errors in logs

Development Workflow

Integrate scoping into development:

• Use scoped credentials in development environments
• Test scope restrictions before production deployment
• Document credential requirements for each application
• Implement proper error handling for scope violations

Common Use Cases

Multi-Tenant SaaS

Customer domain isolation

Create domain-scoped credentials for each customer’s subdomain, preventing cross-customer access

Microservices Architecture

Service-specific credentials

Each microservice gets credentials scoped to its required domains and operations

Marketing & Transactional

Purpose-based separation

Separate credentials for marketing emails vs. transactional notifications

Third-Party Integrations

External service limitations

Provide limited-scope credentials to external services and partners

Related Guides

• API authentication, Send-only API keys, Permission scopes.
• API key CLI, Create key API, IP allow lists.
• Plans and limits.