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

# CLI Authentication: API Keys and Profiles

> Log in to the AhaSend CLI with your API key and account ID, manage separate profiles for production and staging, and pass credentials safely in CI/CD.

The AhaSend CLI saves your API credentials as profiles, so you can work with several accounts or environments.

## Getting Started

Create a full API key under **Account Settings → API Keys**, with the scopes your commands need, and copy the account ID from account settings. See [API authentication](https://ahasend.com/docs/api-reference/authentication.md).

### Interactive Login

```bash theme={null}
ahasend auth login
```

On a terminal, the command asks for your API key and your account ID on stderr, and hides the key as you type it. When stdin is not a terminal, it reads the key and the account ID as two lines of stdin, and empty stdin cancels it with exit code 4; the [auth reference](https://ahasend.com/docs/cli/commands/auth.md#command-flags) shows how to pipe them in. [Profiles](https://ahasend.com/docs/cli/configuration.md#profiles) says which name the profile gets.

Before it saves anything, the command reads the account to check that the key belongs to the account ID:

* A key the API rejects, or a key of another account, fails with exit code 2.
* A key whose IP allow list leaves out this machine fails with exit code 6.
* A key without the scope to read the account belongs to the account, and is saved.

### Direct Login

```bash theme={null}
ahasend auth login \
  --api-key YOUR_API_KEY \
  --account-id YOUR_ACCOUNT_ID \
  --profile production
```

Give both flags or neither: one alone fails with exit code 4. A key passed as a flag can end up in your shell history. Prefer the prompt on your own machine.

### CI Credentials

In CI, skip `auth login`: store the API key and account ID as secrets and pass them with the global flags:

```bash theme={null}
ahasend --api-key "$AHASEND_API_KEY" --account-id "$AHASEND_ACCOUNT_ID" ping
```

The CLI reads no environment variable for credentials or profiles. `--api-key` always uses the production API and cannot be combined with `--profile`. See [CI credentials](https://ahasend.com/docs/cli/configuration.md#ci-credentials) for the rules.

## Profiles

### Creating Profiles

```bash theme={null}
ahasend auth login --profile production
ahasend auth login --profile staging
```

[Profiles](https://ahasend.com/docs/cli/configuration.md#profiles) says which profile becomes the default. When a login keeps another profile as the default, its output says how to switch to the new one. To log in to a profile again, run `auth login` with its name; the login replaces the profile's credentials without asking.

### Switching Profiles

```bash theme={null}
# Change the default profile
ahasend auth switch production

# Use a profile for a single command
ahasend messages send --sandbox --profile staging \
  --from test@staging.example.com \
  --to dev@example.com \
  --subject "Test" --text "Docs test"
```

`auth switch` checks the profile's key first. When the check fails, it prints a warning on stderr and switches anyway.

### Check Status

```bash theme={null}
# Status of the default profile
ahasend auth status

# Status of one profile
ahasend auth status --profile production

# Names of all profiles
ahasend auth status --all
```

`auth status` shows the profile, its account ID, whether the API accepts its key for that account, and the account. It exits nonzero when the key cannot be verified.

### Remove Profiles

```bash theme={null}
# Remove one profile
ahasend auth logout staging

# Remove every profile, after a confirmation prompt
ahasend auth logout --all
```

`auth logout staging` removes the profile at once, without a prompt. You can also name the profile with `--profile`, as in `ahasend auth logout --profile staging`.

`auth logout` without a profile removes the default profile. When you remove the default profile and one profile is left, that profile becomes the default. When several are left, none is the default until you run `ahasend auth switch <profile>`.

## Credential Storage

Profiles live in `~/.ahasend/config.yaml`, which holds your API keys in plain text and is readable by your user only. No `auth` command prints a profile's API key. `apikeys create` and `subaccounts api-keys create` print the new key's secret once, so store it when you create the key. See [Configuration File](https://ahasend.com/docs/cli/configuration.md#configuration-file).

> [!WARNING]
>
> Keep your API keys secure. Never commit credentials to version control.

## Testing Authentication

Verify your setup:

```bash theme={null}
ahasend ping
ahasend auth status
```

`ping` checks that the API can be reached and accepts your key. `auth status` also checks that the key belongs to the profile's account.

## Next Steps

* [Send your first email](https://ahasend.com/docs/cli/quickstart.md)
* [Manage domains](https://ahasend.com/docs/cli/commands/domains.md)
* [Configure webhooks](https://ahasend.com/docs/cli/commands/webhooks.md)

## Related Guides

* [Install the CLI](https://ahasend.com/docs/cli/installation.md), [REST sending guide](https://ahasend.com/docs/send-api/send-email.md), [SMTP settings](https://ahasend.com/docs/smtp.md).
* [Node.js SDK](https://ahasend.com/docs/guides/nodejs-sdk.md), [Go SDK](https://ahasend.com/docs/guides/go-sdk.md), [CLI configuration and output](https://ahasend.com/docs/cli/configuration.md).
* [auth command reference](https://ahasend.com/docs/cli/commands/auth.md), [API authentication](https://ahasend.com/docs/api-reference/authentication.md), [Permission scopes](https://ahasend.com/docs/api-reference/scopes.md).
* [Domain setup](https://ahasend.com/docs/domains.md), [Sandbox behavior](https://ahasend.com/docs/send-api/sandbox.md).


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