Authentication - DialNexa Documentation

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"
}

Endpoint access

The v1 reference includes endpoints exported from the backend with the explicit V1 Swagger tag and documented under Endpoints - v1. These documented v1 endpoints are intended for Bearer API-key access.

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.
Legacy only	Endpoints listed only under Endpoints - Legacy. Keep existing integrations on those paths until a v1 page is published.

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.
Assuming a legacy page has a v1 equivalent when it is not listed under Endpoints - v1.

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

​API keys

​Send the Bearer token

​Endpoint access

​Common mistakes

​Key management best practices

​Webhook signature verification