Authentication
Secure your API requests with three-header authentication. Every request requires your Account ID, API Key, and Secret Key.
How authentication works
Section titled “How authentication works”- Get credentials — Organization → API Key
- Send headers — Include 3 headers with every request
- Verified — Access granted, or error returned
Verify API credentials
Section titled “Verify API credentials”/auth/verify Verifies that your API credentials are valid and returns information about your organization and API key configuration.
Every API request must include all three authentication headers. Missing any header will result in an error.
| Header | Value | Description |
|---|---|---|
X-Account-Id | acc_xxxxxxxx | Your organization identifier |
X-Api-Key | pk_xxxxxxxxxxxxxxxxxx | Public API key |
X-Secret-Key | sk_xxxxxxxxxxxxxxxxxx | Secret key — keep confidential |
curl -X POST \ https://app.dutiesbook.com/api/external/v1/auth/verify \ -H "X-Account-Id: acc_xxxxxxxx" \ -H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \ -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"// Node.js 18 or later (built-in fetch)const response = await fetch('https://app.dutiesbook.com/api/external/v1/auth/verify', { method: 'POST', headers: { 'X-Account-Id': process.env.DUTIES_ACCOUNT_ID, 'X-Api-Key': process.env.DUTIES_API_KEY, 'X-Secret-Key': process.env.DUTIES_SECRET_KEY, },});
const result = await response.json();import osimport requests
response = requests.post( "https://app.dutiesbook.com/api/external/v1/auth/verify", headers={ "X-Account-Id": os.environ["DUTIES_ACCOUNT_ID"], "X-Api-Key": os.environ["DUTIES_API_KEY"], "X-Secret-Key": os.environ["DUTIES_SECRET_KEY"], },)
result = response.json(){ "success": true, "data": { "valid": true, "organization": { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "Your Organization Name" }, "apiKey": { "name": "Your API Key Name", "accessType": "specific_ips", "id": "xxxxxxxxxxxxxxxxxxxx" } }}{ "success": false, "error": { "code": "AUTH_005", "message": "Invalid credentials. The provided Account ID, API Key, and Secret Key do not match." }}IP restrictions
Section titled “IP restrictions”API keys can be restricted to specific IP addresses or CIDR ranges:
- All IPs — Key works from any IP address. Good for development environments.
- Specific IPs — Key only works from whitelisted IPs. Recommended for production.
When a request comes from a non-whitelisted IP:
{ "success": false, "error": { "code": "AUTH_006", "message": "IP address not allowed" }}Authentication errors
Section titled “Authentication errors”AUTH_001 401 Missing required credentials. Provide X-Account-Id, X-Api-Key, and X-Secret-Key headers.
AUTH_002 401 Invalid Account ID format.
AUTH_003 401 Invalid API Key format.
AUTH_004 401 Invalid Secret Key format.
AUTH_005 401 Invalid credentials. The provided Account ID, API Key, and Secret Key do not match.
AUTH_006 403 IP address not allowed. Your IP is not in the whitelist for this API key.
AUTH_007 403 This API key does not have the permission required for this action (e.g. a test key attempting a production-only action).
AUTH_008 403 This API key is restricted to specific channels and does not have access to the requested channel.
Security best practices
Section titled “Security best practices”- Store credentials securely — Use environment variables, never commit to code
- Rotate keys periodically — Change API keys every 90 days
- Use IP restrictions — Whitelist only your server IPs in production
- Monitor API usage — Watch for unexpected patterns or unauthorized access
- Use separate keys — Different keys for development and production
- Use HTTPS only — All API communications must use HTTPS
Creating API keys
Section titled “Creating API keys”- Log in to dashboard — Access your account dashboard at your organization’s portal.
- Navigate to API keys — Go to Organization → API Key
- Create new key — Click Create API Key button.
- Configure settings — Set a name, select permissions, configure IP restrictions, and optionally limit to specific channels. The Appointments API (Enterprise plans only) needs the Appointments permission; a key limited to specific channels also needs your appointments WhatsApp number among them.
- Save credentials — Copy and securely store your Account ID, API Key, and Secret Key. The Secret Key is only shown once!
Important: The Secret Key is only shown once at creation. Store it securely immediately. If you lose it, you’ll need to create a new API key.