> ## 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.

# API Authentication with Bearer API Keys

> Authenticate AhaSend API v2 requests with an aha-sk- API key in an Authorization: Bearer header. Create a key, test it and keep it secure.

AhaSend uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Available on Free, Pro and Max. See [plans and features](https://ahasend.com/docs/facts.md#plans-and-features).

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

The API base URL is `https://api.ahasend.com`. Find your account ID in the dashboard account settings. Message-list examples below need a full API key with `messages:read:{your-domain}` or `messages:read:all`.

## API Key Format

AhaSend API keys follow this format:

```text theme={null}
aha-sk-64-CHARACTER-RANDOM-STRING
```

> [!WARNING]
>
> Keep your API keys secure and never expose them in client-side code, version control, or logs.

## Obtaining Your API Key

For management tasks, create a full API key as follows. For send-only applications, use **Credentials → Add → API Key v2** instead; see [send-only API keys](https://ahasend.com/docs/send-api/credentials.md).

1. Log in to your AhaSend dashboard
2. Open **Account Settings → API Keys** at [API Keys](https://dash.ahasend.com/account/-/settings/api-keys)
3. Click "Create API Key"
4. Select the appropriate [scopes](https://ahasend.com/docs/api-reference/scopes.md) for your use case
5. Copy and securely store your new API key

> [!NOTE]
>
> API keys are only displayed once during creation. Make sure to copy and store them securely.

> [!TIP]
>
> You can restrict a key to specific IP addresses so it cannot be used from anywhere else. See [IP Allow Lists](https://ahasend.com/docs/security/ip-allow-lists.md).

## Making Authenticated Requests

Authentication to the API is performed via HTTP Bearer Authentication. Provide your API key in the `Authorization` header:

```bash cURL theme={null}
curl https://api.ahasend.com/v2/accounts/YOUR_ACCOUNT_ID/messages \
  -H "Authorization: Bearer aha-sk-your-api-key-here" \
  -H "Content-Type: application/json"
```

```javascript Node.js theme={null}
const response = await fetch('https://api.ahasend.com/v2/accounts/YOUR_ACCOUNT_ID/messages', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer aha-sk-your-api-key-here',
    'Content-Type': 'application/json'
  }
});
```

```python Python theme={null}
import requests

headers = {
    'Authorization': 'Bearer aha-sk-your-api-key-here',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.ahasend.com/v2/accounts/YOUR_ACCOUNT_ID/messages', headers=headers)
```

```php PHP theme={null}
<?php
$headers = [
    'Authorization: Bearer aha-sk-your-api-key-here',
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.ahasend.com/v2/accounts/YOUR_ACCOUNT_ID/messages');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
```

```ruby Ruby theme={null}
require 'net/http'
require 'uri'

uri = URI('https://api.ahasend.com/v2/accounts/YOUR_ACCOUNT_ID/messages')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer aha-sk-your-api-key-here'
request['Content-Type'] = 'application/json'

response = http.request(request)
```

```go Go theme={null}
package main

import (
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.ahasend.com/v2/accounts/YOUR_ACCOUNT_ID/messages", nil)
    req.Header.Add("Authorization", "Bearer aha-sk-your-api-key-here")
    req.Header.Add("Content-Type", "application/json")

    resp, _ := client.Do(req)
    defer resp.Body.Close()
}
```

## Security Best Practices

> [card] Server-Side Only
>
> Only use API keys in server-side applications. Never include them in client-side code.

> [card] Secure Storage
>
> Store API keys in environment variables or secure configuration management systems.

> [card] Principle of Least Privilege
>
> Create API keys with only the minimum scopes required for your use case.

> [card] Regular Rotation
>
> Regularly rotate your API keys and immediately revoke any compromised keys.

### Environment Variables

Store your API key as an environment variable:

```bash Linux/macOS theme={null}
export AHASEND_API_KEY="aha-sk-your-api-key-here"
```

```powershell Windows theme={null}
$env:AHASEND_API_KEY="aha-sk-your-api-key-here"
```

```javascript Node.js theme={null}
// Use process.env to access the API key
const apiKey = process.env.AHASEND_API_KEY;
```

```python Python theme={null}
import os

api_key = os.environ.get('AHASEND_API_KEY')
```

## Testing Authentication

You can test your authentication by making a simple request to the [Ping utility endpoint](https://ahasend.com/docs/api-reference/utility/ping.md):

```bash cURL theme={null}
curl https://api.ahasend.com/v2/ping \
  -H "Authorization: Bearer aha-sk-your-api-key-here"
```

```javascript Node.js theme={null}
const response = await fetch('https://api.ahasend.com/v2/ping', {
  headers: {
    'Authorization': 'Bearer aha-sk-your-api-key-here'
  }
});

if (response.ok) {
  console.log('Authentication successful!');
  const account = await response.json();
  console.log(account);
} else {
  console.log('Authentication failed:', response.status);
}
```

> [!TIP]
>
> If you're getting authentication errors, double-check that your API key is correct and that it has the necessary scopes for the endpoint you're trying to access.

## Next Steps

Now that you understand authentication, you can:

* Explore [API Scopes](https://ahasend.com/docs/api-reference/scopes.md) to understand permission levels
* Check [Rate Limits](https://ahasend.com/docs/api-reference/rate-limits.md) to understand usage restrictions
* Start [sending messages](https://ahasend.com/docs/api-reference/messages/create-message.md) with the API

## Related Guides

* [Permission scopes](https://ahasend.com/docs/api-reference/scopes.md), [Send-only API keys](https://ahasend.com/docs/send-api/credentials.md), [REST sending guide](https://ahasend.com/docs/send-api/send-email.md).
* [SMTP settings](https://ahasend.com/docs/smtp.md), [CLI quickstart](https://ahasend.com/docs/cli/quickstart.md), [Node.js SDK](https://ahasend.com/docs/guides/nodejs-sdk.md).
* [Go SDK](https://ahasend.com/docs/guides/go-sdk.md), [API errors](https://ahasend.com/docs/api-reference/errors.md), [API rate limits](https://ahasend.com/docs/api-reference/rate-limits.md).


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