# Creating API Keys

Generate API keys with scoped permissions

API keys authenticate programmatic access to your Mailnaptic account. Each key is scoped to specific permissions, so you can create keys that only have access to the resources they need. This follows the principle of least privilege and limits the impact if a key is compromised.

## Generating a new API key

1. Navigate to **Organization → API Keys**.
2. Click **Create API Key**.
3. Enter a descriptive **name** for the key (e.g., "Website contact form", "CRM sync", "Analytics export").
4. Select the **permission scopes** the key requires. See *API Key Scopes* for a full list.
5. Click **Generate**.
6. The key is displayed **once**. Copy it immediately and store it securely. You will not be able to view it again.

## Key format

Mailnaptic API keys are prefixed with `mn_` followed by a 48-character random string:

```
mn_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4
```

The prefix makes it easy to identify Mailnaptic keys in your codebase or secret manager, and enables secret scanning tools to flag accidental exposure.

## Storing keys securely

Follow these best practices for API key storage:

- **Environment variables:** Store keys in environment variables, not in source code. 
 ```
 export MAILNAPTIC_API_KEY="mn_your_key_here"
 ```
- **Secret managers:** Use AWS Secrets Manager, HashiCorp Vault, or your platform's equivalent.
- **Never commit keys to version control.** Add `.env` to your `.gitignore`.
- **Never expose keys in client-side code.** API calls should be made from your backend server.

## Managing existing keys

On the API Keys page, you can:

| Action | Description |
| --- | --- |
| **View details** | See the key's name, scopes, creation date, and last used timestamp |
| **Revoke** | Permanently disable the key. This takes effect immediately — any requests using the key will return `401` |

You cannot edit a key's scopes after creation. If you need different permissions, create a new key and revoke the old one.

## Key rotation

Periodically rotating API keys reduces the risk of compromise. A good rotation workflow:

1. Create a new key with the same scopes as the existing one.
2. Update your application to use the new key.
3. Verify the new key works correctly.
4. Revoke the old key.

During the transition, both keys are active simultaneously, so there is no downtime.

## Auditing key usage

Each API key shows a **last used** timestamp on the API Keys page. Review this periodically to identify unused keys that can be revoked. Keys that haven't been used in 90+ days are good candidates for revocation.

## Limits

Each organization can create up to **25 API keys**. If you need more, revoke unused keys first. Each key is subject to the standard API rate limits described in the *API Overview*.

> **Important:** API keys provide full access within their scopes without requiring additional authentication (no CSRF, no session). Treat them with the same care as passwords.
