Skip to content
DutiesBook API
Open app

Authentication

Secure your API requests with three-header authentication. Every request requires your Account ID, API Key, and Secret Key.

  1. Get credentials — Organization → API Key
  2. Send headers — Include 3 headers with every request
  3. Verified — Access granted, or error returned
POST /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.

HeaderValueDescription
X-Account-Idacc_xxxxxxxxYour organization identifier
X-Api-Keypk_xxxxxxxxxxxxxxxxxxPublic API key
X-Secret-Keysk_xxxxxxxxxxxxxxxxxxSecret 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"
200 OK
{
"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"
}
}
}
401 Unauthorized
{
"success": false,
"error": {
"code": "AUTH_005",
"message": "Invalid credentials. The provided Account ID, API Key, and Secret Key do not match."
}
}

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:

403 Forbidden
{
"success": false,
"error": {
"code": "AUTH_006",
"message": "IP address not allowed"
}
}
AUTH_001 401
MISSING_CREDENTIALS

Missing required credentials. Provide X-Account-Id, X-Api-Key, and X-Secret-Key headers.

AUTH_002 401
INVALID_ACCOUNT_ID

Invalid Account ID format.

AUTH_003 401
INVALID_API_KEY

Invalid API Key format.

AUTH_004 401
INVALID_SECRET_KEY

Invalid Secret Key format.

AUTH_005 401
CREDENTIALS_MISMATCH

Invalid credentials. The provided Account ID, API Key, and Secret Key do not match.

AUTH_006 403
IP_NOT_ALLOWED

IP address not allowed. Your IP is not in the whitelist for this API key.

AUTH_007 403
PERMISSION_DENIED

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
CHANNEL_ACCESS_DENIED

This API key is restricted to specific channels and does not have access to the requested channel.

  • 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
  1. Log in to dashboard — Access your account dashboard at your organization’s portal.
  2. Navigate to API keys — Go to Organization → API Key
  3. Create new key — Click Create API Key button.
  4. 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.
  5. 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.