Authentication

How to authenticate requests to the DialNexa API with Bearer API keys and understand v1 endpoint access.

DialNexa API requests use a Bearer API key in the Authorization header. The key identifies your workspace and authorizes access to endpoints that are available to API clients.

API keys

Create and manage API keys in the DialNexa dashboard under Settings > API Keys. An API key has two parts separated by a colon. The full value must be sent as the Bearer token.

Example: abcdefghijklmn:123456a1b1234b

The segment before the colon is the key ID. The segment after the colon is the secret. Treat the full key like a password. Do not commit it to source control or expose it in browser code.

Send the Bearer token

Pass the API key in the Authorization header on every API-key request.

curl https://api.dialnexa.com/v1/voices \
  -H "Authorization: Bearer YOUR_API_KEY"

A missing, revoked, or malformed key returns 401 Unauthorized.

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

API access

Every operation listed under Endpoints supports Bearer API-key authentication.

Access type	Endpoints
Bearer API key	Agents, calls, batch calls, workflows and workflow leads, user webhooks, voices, languages, LLMs, transcribers including fallback transcribers, knowledge-base create/read/update/delete, and phone-number list/get/search/purchase/SIP-trunk/delete operations.

Common mistakes

• Sending only the key ID instead of the full key_id:secret value.
• Using x-api-key instead of the Bearer Authorization header for v1 endpoints.
• Omitting /v1 from the configured API base URL.

Key management best practices

• Use one key per environment, such as development, staging, and production.
• Rotate keys on a schedule and immediately after suspected exposure.
• Store keys in environment variables or a secrets manager.
• Remove unused keys from the dashboard.

Webhook signature verification

Incoming webhook payloads from DialNexa are signed with HMAC-SHA256 using the secret configured for that webhook. Verify the x-nexa-signature header before trusting the payload.

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)
  );
}