# API keys

> Create API keys with the least access they need, restrict them to a domain, and rotate them safely.

API keys authenticate your server with the Nexiom Connect API. Each key belongs to one project; everything it creates or reads stays in that project.

## Create a key

In the dashboard, open **API keys** and select **Create API key**. Choose:

- **Name** — describes where the key is used, such as `production-web` or `billing-worker`.
- **Permission** — what the key can do. See below.
- **Domain** — optionally restrict sending to a single verified domain.
- **Expiration** — never, or after 7 days, 30 days, 90 days, or 1 year.

The full key is shown once, when it is created. Keys start with `nc_`. Store the key in your secret manager or environment, never in source control or browser code.

## Permissions

| Permission | Dashboard label | Allows |
| --- | --- | --- |
| `email.send` | Email send only | [Sending email](/docs/api/emails/send), and canceling or rescheduling scheduled emails. |
| `email.full_access` | Email full access | Everything `email.send` allows, plus domains, email logs, and contacts. |
| `whatsapp.send` | WhatsApp send only | [Sending WhatsApp messages](/docs/api/messaging/send) and [reading them](/docs/api/messaging/retrieve). |
| `whatsapp.full_access` | WhatsApp full access | Everything `whatsapp.send` allows. |

A key can hold email and WhatsApp permissions together. Each full access permission includes only its own channel's send permission: `email.full_access` doesn't allow sending WhatsApp messages, and `whatsapp.full_access` doesn't allow sending email. The WhatsApp permissions are offered only to organizations with WhatsApp turned on.

Use **Email send only** or **WhatsApp send only** for application servers that only send. Reserve full access for back-office tools that manage domains or read logs. A request without the required permission returns `403` with error `not_allowed`.

## Restrict a key to one domain

A key restricted to a domain can only send email from addresses on that domain. The restriction doesn't apply to WhatsApp messages. Restricting keys limits the impact of a leaked key, and makes it easy to give each product or team its own sender.

## Authenticate requests

Send the key as a bearer token:

```http
Authorization: Bearer nc_your_api_key
```

The key alone determines the organization and project. Never include organization or project identifiers in requests.

## Rotate a key

Rotate keys regularly and immediately if one may have leaked:

### Rotate it in the dashboard

Select **Rotate** on the key. You receive a new secret; the old one stops working.

### Update your deployments

Replace the stored secret in every environment that uses the key, then restart or reload those services.

### Confirm traffic

Check the key's **Last used** time and your [email logs](/docs/learn/email-activity) to confirm requests succeed with the new secret.

> [!TIP]
> To rotate without any failed requests, create a second key first, deploy it everywhere, and then delete the old key.

You can also revoke a key and re-activate it later, or delete it permanently. Requests with a revoked, expired, or deleted key return `401 Unauthorized`.

## Best practices

- Create one key per application and environment, so you can rotate or revoke one without affecting others.
- Give each key the narrowest permission and domain it needs.
- Set an expiration for keys used in temporary or shared environments.
- Never log API keys. Nexiom Connect shows only a key's last characters after creation.

---

Source: https://connect.nxiom.com/docs/learn/api-keys