NexaDesk

Authentication

API key management, scopes, and security for the NexaDesk API

The NexaDesk API uses API keys for authentication. Each key is scoped to a specific workspace and set of permissions.

API Key Format

API keys follow this format:

fc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys start with fc_live_ followed by a random alphanumeric string. Store your keys securely and never expose them in client-side code.

Creating an API Key

  1. Go to Settings > API Keys in your NexaDesk dashboard
  2. Click Create API Key
  3. Enter a name for the key (e.g., "Zapier Integration", "Internal CRM Sync")
  4. Select scopes:
    • read — Access to GET endpoints (list and retrieve resources)
    • write — Access to POST, PATCH, DELETE endpoints (create, update, delete resources)
  5. Optionally configure IP whitelisting (see below)
  6. Click Create
  7. Copy the key immediately — it will not be shown again

Using the API Key

Include the key as a Bearer token in the Authorization header:

bash
curl https://chats.nexadesk.ai/api/v1/external/leads \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx"

Scopes

ScopeAccess
readGET endpoints — list and retrieve leads, contacts, conversations
writePOST, PATCH, DELETE endpoints — create, update, delete resources

A key with only read scope will receive a 403 Forbidden error when attempting write operations.

IP Whitelisting

For added security, restrict API key usage to specific IP addresses:

  1. Edit the API key in Settings > API Keys
  2. Add one or more IP addresses (IPv4 or IPv6)
  3. Save

Requests from non-whitelisted IPs will receive a 403 Forbidden response. Leave the whitelist empty to allow requests from any IP.

Rate Limits

Each API key is rate limited to 100 requests per minute using a sliding window. When the limit is exceeded:

  • The API returns 429 Too Many Requests
  • The Retry-After header indicates how many seconds to wait

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1711843200

Usage Tracking

API usage is tracked per key. View usage statistics in Settings > API Keys > [Key Name] > Usage:

  • Total requests (today, this week, this month)
  • Requests by endpoint
  • Error rate
  • Rate limit hits

Revoking Keys

To revoke an API key:

  1. Go to Settings > API Keys
  2. Click the menu icon on the key you want to revoke
  3. Click Revoke
  4. Confirm the action

Revoked keys are immediately invalidated. Any integration using the key will start receiving 401 Unauthorized responses.

Security Best Practices

  • Never expose keys in client-side code — API keys should only be used from server-side applications
  • Use the minimum required scope — If your integration only reads data, create a read-only key
  • Enable IP whitelisting — Restrict keys to known server IPs when possible
  • Rotate keys regularly — Create new keys and revoke old ones periodically
  • Use separate keys per integration — If one is compromised, you can revoke it without affecting others
PreviousGetting StartedNextLeads