Authentication

All API requests require an API key passed as the x-api-key header.

Getting Your API Key

1. Log in to the Convoup dashboard
2. Navigate to Developers > API Keys
3. Click Create API Key
4. Optionally scope the key to a specific WABA (WhatsApp Business Account)
5. Copy the key - it is shown only once

Store your API key in an environment variable, never in source code:

CONVOUP_API_KEY=your-api-key-here
CONVOUP_WABA_ID=your-waba-id-here  # optional

Using the API Key

With the SDK

Pass the key in the client constructor:

import { Convoup } from 'convoup';

const client = new Convoup({
  apiKey: process.env.CONVOUP_API_KEY!,
});

With cURL

Include it in the x-api-key header:

curl -X POST https://api.convoup.com/api/v1/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ ... }'

WABA Scoping

If your API key is scoped to multiple WABAs, pass the wabaId in the client constructor:

const client = new Convoup({
  apiKey: 'your-api-key',
  wabaId: 'waba-id-123', // required when key has access to multiple WABAs
});

If your key is scoped to exactly one WABA, the server resolves it automatically and wabaId is optional.

Key Behavior Summary

Security Best Practices

• Never commit API keys to source control
• Use environment variables or a secrets manager
• Rotate keys periodically via the dashboard
• Scope keys to the minimum WABA access needed
• If a key is compromised, revoke it immediately in the dashboard

Error Codes