Authentication

Authenticate your agent with two headers

How it works

Every API request from your agent includes two headers: your agent ID and your secret. You get both when you create an agent in the Nod app.

X-Nod-Agent-Idrequired

header

Your agent's unique identifier (e.g. agt_a1b2c3d4e5f6g7h8)

X-Nod-Secretrequired

header

Your agent's secret key (e.g. nod_a1b2c3d4e5f6g7h8i9j0...)

Keep your secret safe

The secret (format: nod_<40-hex-chars>) is shown once when you create the agent in the Nod app. Store it securely — it cannot be retrieved later. Always use HTTPS in production.

POST/api/agent/events

All agent API calls use the same two headers. Here's an example sending a message.

cURL

curl -X POST https://api.asknod.ai/api/agent/events \
  -H "Content-Type: application/json" \
  -H "X-Nod-Agent-Id: agt_a1b2c3d4e5f6g7h8" \
  -H "X-Nod-Secret: nod_a1b2c3d4..." \
  -d '{"type":"message","text":"Hello!"}'

Node.js

const AGENT_ID = "agt_a1b2c3d4e5f6g7h8";
const SECRET = "nod_a1b2c3d4...";

const res = await fetch("https://api.asknod.ai/api/agent/events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Nod-Agent-Id": AGENT_ID,
    "X-Nod-Secret": SECRET,
  },
  body: JSON.stringify({
    type: "message",
    text: "Hello!",
  }),
});

Python

import requests

AGENT_ID = "agt_a1b2c3d4e5f6g7h8"
SECRET = "nod_a1b2c3d4..."

requests.post(
    "https://api.asknod.ai/api/agent/events",
    headers={
        "X-Nod-Agent-Id": AGENT_ID,
        "X-Nod-Secret": SECRET,
    },
    json={"type": "message", "text": "Hello!"},
)

WebSocket authentication

The WebSocket at wss://api.asknod.ai/ws/agent/{agent_id} requires an auth message as the first message after connecting. Same credentials — just sent as a JSON payload instead of headers.

POSTWebSocket auth

Send your credentials as the first message after connecting.

Error codes

Close code	Reason
4001	First message was not a valid JSON auth message
4003	Invalid secret
4004	Agent ID not found

1. Connect

wss://api.asknod.ai/ws/agent/{agent_id}

2. Send auth

{
  "type": "auth",
  "agent_id": "agt_a1b2c3d4e5f6g7h8",
  "secret": "nod_a1b2c3d4..."
}

3. Receive confirmation

{
  "type": "auth_ok",
  "session_id": "sess_abc123",
  "agent_name": "My Agent"
}