Skip to main content
API keys authenticate your applications to the DialNexa REST API. Any request that reads or modifies your agents, calls, phone numbers, or account data requires a valid API key in the Authorization header.

​
How API Keys Work

Include your API key as a Bearer token in the Authorization header of every API request: 
curl https://api.dialnexa.com/v1/calls \
  -H "Authorization: Bearer dnx_live_xxxxxxxxxxxxxxxxxxxxxxxx"
API keys are prefixed to indicate their type:
  • dnx_live_ - live keys that affect real calls and billing
  • dnx_test_ - test keys for development (calls are simulated, no telephony is initiated, no billing occurs)
Never use a live key in development or staging environments. Always use test keys for non-production work.

​
Creating an API Key

1

Open API Keys settings

Go to Settings → API Keys in the dashboard. You’ll see a list of all existing keys.
2

Click Create New Key

Click the + New API Key button in the top right.
3

Name the key

Give the key a descriptive name that identifies the service using it (e.g., “Production CRM Integration”, “Batch Campaign Service”, “Staging Test Key”). Names are for your reference only and do not affect key behavior.
4

Select key type

Choose Live or Test. Test keys behave identically to live keys in terms of API responses, but do not initiate real calls or incur charges.
5

Copy and save the key

The full key value is shown only once, immediately after creation. Copy it and store it in your secrets manager. You cannot retrieve the full key value again after this screen.
After creation, only the last 4 characters of the key are visible in the dashboard (e.g., dnx_live_...xxxx). This is intentional - it lets you identify keys without exposing them.

​
Key Permissions

By default, a new API key has full access to all resources within the workspace it belongs to. If you want more granular control, you can restrict a key’s permissions when creating it:
PermissionWhat it allows
calls:readRead call history, transcripts, recordings
calls:writeInitiate outbound calls, manage campaigns
agents:readRead agent configurations
agents:writeCreate, update, delete agents
phone_numbers:readList phone numbers
phone_numbers:writePurchase, configure, release phone numbers
analytics:readRead usage metrics and reports
billing:readView wallet balance and invoices
Principle of least privilege: Give each key only the permissions it needs. A key used only to retrieve call transcripts should have calls:read only, not calls:write or agents:write.

​
Rotating API Keys

Key rotation replaces an existing key with a new one, invalidating the old one. Rotate keys:
  • Every 90 days as a standard security practice
  • Immediately after any team member departure (if they had access to the key)
  • Immediately after a suspected or confirmed key exposure
How to rotate:
1

Create a new key

Follow the key creation steps above to generate a replacement key with the same permissions as the key being rotated.
2

Update your application

Replace the old key with the new key in your application’s environment variables or secrets manager. Deploy the updated configuration.
3

Verify the new key is working

Confirm that your application is successfully authenticating with the new key by checking API call logs or the key’s last-used timestamp in the dashboard.
4

Revoke the old key

Once you have confirmed the new key is operational, revoke the old key immediately. Do not leave both keys active longer than necessary.

​
Revoking an API Key

To revoke a key:
  1. Go to Settings → API Keys
  2. Find the key you want to revoke
  3. Click the Revoke button (trash icon) on that key’s row
  4. Confirm the revocation
Revocation is immediate and permanent. Any application using the revoked key will receive 401 Unauthorized errors on all subsequent requests. There is no grace period.
Before revoking a key, make sure no production systems are still using it. Revoking an active key will break any services that depend on it.

​
Monitoring API Key Usage

The API Keys dashboard shows usage statistics for each key:
  • Last used: timestamp of the most recent authenticated request
  • Total requests (30 days): request count over the last 30 days
  • Last IP: the IP address from which the last request was made
Review these periodically. If a key shows usage from an unexpected IP address or an unusually high request count, investigate immediately.

​
Security Best Practices

PracticeWhy it matters
Store keys in environment variables or a secrets managerPrevents accidental exposure in source code or logs
Never commit keys to version controlRepositories (even private ones) can be leaked or scraped
Never log API keysLog files are often less protected than application secrets
Never embed keys in client-side codeBrowser JavaScript is visible to anyone - keys will be extracted
Use separate keys per serviceLimits blast radius if one key is compromised
Use test keys for developmentPrevents accidental real calls or charges during testing
Rotate keys every 90 daysLimits the window of exposure if a key was silently compromised
Revoke unused keysEvery active key is an unnecessary attack surface

​
Workspace Scope

API keys belong to a specific workspace. A key from Workspace A cannot access agents, calls, or phone numbers in Workspace B. If you operate multiple workspaces (e.g., for different clients or environments), create separate API keys for each workspace. Organization-level API keys (available on Enterprise plans) have cross-workspace access. See Organization and Members for details.