> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# 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](https://ahasend.com/docs/facts.md#plans-and-features).

> [!NOTE]
>
> **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:

> [card] Sending Credentials
>
> **SMTP & API v1/v2 sending keys**
>
> Domain-scoped credentials for email sending operations only

> [card] 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](https://dash.ahasend.com/account/-/transactional/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

> [!NOTE]
>
> **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](https://ahasend.com/docs/send-api/credentials.md) or [SMTP credential setup](https://ahasend.com/docs/smtp/credentials.md), and choose only the sending domains your application needs.

## API v2 Keys (Advanced Scoping)

API v2 keys are created from **Account Settings** → **[API Keys](https://dash.ahasend.com/account/-/settings/api-keys)** and provide full access to the AhaSend API v2 with granular permission and domain scoping.

> [!TIP]
>
> **Restrict by IP as well:** API v2 keys can also be limited to a set of IP addresses. See [IP Allow Lists](https://ahasend.com/docs/security/ip-allow-lists.md).

### 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](https://ahasend.com/docs/api-reference/authentication.md) for the creation steps and [scopes](https://ahasend.com/docs/api-reference/scopes.md) 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:

> [accordion] SMTP Authentication Error
>
> **SMTP Connection Rejected:**
>
> ```plaintext theme={null}
> authz_id 'YOUR_USERNAME' is not authorized to send as tenant 'YOUR_ACCOUNT_ID' or from this domain
> ```

> [accordion] API v1 Error
>
> **API v1 Request Error:**
>
> ```json theme={null}
> {
>   "status": "API Key is not scoped for this domain"
> }
> ```

> [accordion] API v2 Sending Error
>
> **API v2 Request Error:**
>
> ```json theme={null}
> {
>   "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:

> [accordion] Permission Scope Errors
>
> **Insufficient Permissions:**
>
> ```json theme={null}
> {"message": "Insufficient permissions"}
> ```
>
> **Resource Access Denied:**
>
> ```json theme={null}
> {"message": "Access denied"}
> ```

> [accordion] Domain Scope Errors
>
> **Domain Not Authorized:**
>
> ```json theme={null}
> {
>   "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

> [!NOTE]
>
> **Detailed Documentation:** For complete scope definitions, validation rules, and examples, see our [API Scopes Reference](https://ahasend.com/docs/api-reference/scopes.md).

## Benefits and Best Practices

Scoped credentials provide significant advantages regardless of type:

### Security Benefits

> [accordion] 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

> [accordion] Improved Control
>
> **Granular access management:**
>
> * Separate credentials for different applications
> * Team-specific permissions and domain access
> * Environment-specific scoping (staging vs. production)

> [accordion] Error Prevention
>
> **Prevent configuration mistakes:**
>
> * Block accidental sending from wrong domains
> * Catch misconfigurations early in development
> * Protect production domains from test applications

> [accordion] 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

> [accordion] 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

> [accordion] 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

> [accordion] 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

> [card] Multi-Tenant SaaS
>
> **Customer domain isolation**
>
> Create domain-scoped credentials for each customer's subdomain, preventing cross-customer access

> [card] Microservices Architecture
>
> **Service-specific credentials**
>
> Each microservice gets credentials scoped to its required domains and operations

> [card] Marketing & Transactional
>
> **Purpose-based separation**
>
> Separate credentials for marketing emails vs. transactional notifications

> [card] Third-Party Integrations
>
> **External service limitations**
>
> Provide limited-scope credentials to external services and partners

## Related Guides

* [API authentication](https://ahasend.com/docs/api-reference/authentication.md), [Send-only API keys](https://ahasend.com/docs/send-api/credentials.md), [Permission scopes](https://ahasend.com/docs/api-reference/scopes.md).
* [API key CLI](https://ahasend.com/docs/cli/commands/apikeys.md), [Create key API](https://ahasend.com/docs/api-reference/api-keys/create-api-key.md), [IP allow lists](https://ahasend.com/docs/security/ip-allow-lists.md).
* [Plans and limits](https://ahasend.com/docs/facts.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.