Skip to main content

​
API keys

All requests to the DialNexa API must be authenticated using an API key. You can create and manage API keys in the DialNexa dashboard under Settings > API Keys, or programmatically via the API Keys endpoints. An API key has two parts separated by a colon: 
Example: abcdefghijklmn:123456a1b1234b
The segment before the colon is the key ID (public identifier). The segment after the colon is the secret (treat it like a password). Both parts are required, pass the full string as the Bearer token. Keep your API keys secure. Do not commit them to source control or expose them in client-side code. Use environment variables or a secrets manager to store them.

​
Bearer token

Pass your API key as a Bearer token in the Authorization header on every request: 
Authorization: Bearer YOUR_API_KEY

​
Example

curl https://api.dialnexa.com/v1/agents2 \
  -H "Authorization: Bearer YOUR_API_KEY"
Without a valid key, the API returns 401 Unauthorized: 
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

​
Creating an API key

curl -X POST https://api.dialnexa.com/v1/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Server"}'
The response includes the key’s secret field. This value is only returned once, copy it immediately and store it securely. You cannot retrieve the secret after this initial response. 
{
  "id": "abcgvvzzlrbnqy",
  "name": "Production Server",
  "secret": "YOUR_API_KEY",
  "created_at": "2024-03-01T10:00:00.000Z"
}

​
Key management best practices

  • One key per environment: Create separate keys for development, staging, and production. This makes it easy to rotate a key in one environment without affecting others.
  • Rotate regularly: Revoke and replace keys on a schedule, or immediately if you suspect a key has been compromised.
  • Least privilege: If you are building a read-only integration (for example, fetching call logs to display in a dashboard), use a dedicated key for that integration. Revoke it independently if needed.

​
Revoking a key

curl -X DELETE https://api.dialnexa.com/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
Once revoked, all requests using that key immediately return 401 Unauthorized.

​
Webhook signature verification

Incoming webhook payloads from DialNexa are signed with HMAC-SHA256 using the secret you provided when registering the webhook. Verify the X-DialNexa-Signature header on every incoming request to confirm the payload originated from DialNexa. 
import hmac
import hashlib

def verify_webhook(payload_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

import * as crypto from "crypto";

function verifyWebhook(
  payloadBody: Buffer,
  signatureHeader: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payloadBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}
Always use a constant-time comparison function (such as hmac.compare_digest in Python or crypto.timingSafeEqual in Node.js) to prevent timing attacks.