Authentication and API keys

API key anatomy

Every public request is scoped by the API key to one Yanola Account, one Agent Project, one environment, a set of permissions, and optionally selected Senders. You do not pass an agent ID in public API paths.

Authenticate with the SDK

WhatsAppClient adds the Bearer Authorization header to every request. Pass the credential through YANOLA_API_KEY rather than constructing headers yourself.

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

Authenticate with REST

For direct HTTP integrations, send the same credential using the Bearer scheme. The production API begins at https://api.yanola.ai/v1.

curl "https://api.yanola.ai/v1/senders" \
  --header "Authorization: Bearer $YANOLA_API_KEY" \
  --header "Accept: application/json"

Choose least-privilege scopes

Scopes are selected in the Agent Project dashboard. The default preset excludes webhooks:write so a key cannot replay deliveries unless you explicitly grant that capability.

Restrict Sender access

A key can be allowed to use every eligible Sender in its Agent Project or only selected connected numbers. Sender restrictions apply in addition to scopes; messages:write does not grant access to a number outside the key's allowed set.

Use separate narrowly scoped keys for independent services instead of sharing one broad production credential.

Store credentials safely

1. Use YANOLA_API_KEY in a local ignored file for development and a secret manager in deployed environments.
2. Create different credentials for development, staging, and production services.
3. Do not log the key, place it in client-side state, commit it, send it in job payloads, or expose it through browser-prefixed variables.
4. Rotate immediately if a credential may have been copied to an unsafe location.

.env
.env.local
.env.*.local

Lifecycle management

API key lifecycle operations are dashboard-only in v1. A public API key cannot create or modify other credentials.

1. Create a key in either the Test Mode or Live Mode tab and copy its secret once.
2. Rename it to identify the owning service and environment.
3. Adjust scopes, expiration, and allowed Senders as access needs change.
4. Rotate to replace the secret immediately while keeping the key ID and access settings.
5. Revoke to permanently disable the key; revoked keys cannot be rotated back into service.
6. Review last-used metadata and audit events when investigating credential activity.

Authentication failures