API keys

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#

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:

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:

1. Rotate it in the dashboard

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

2. Update your deployments

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

3. Confirm traffic

   Check the key's Last used time and your email logs to confirm requests succeed with the new secret.

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.