Authentication

Secret keys, publishable keys, scopes and session tokens for the front end.

The API uses three types of credential. Each one has its proper place.

Secret keys

Send it in the Authorization header:

curl https://api.nevox.ai/v1/agents \
  -H "Authorization: Bearer nvx_sk_live_..."

Management

• Only the account owner can generate keys, in Dashboard → Developers → API keys.
• The key is shown only once. Nevox stores only an encrypted version (hash). If you lose it, generate another one.
• You can have several keys (one per system) and revoke any of them instantly. Revocation takes effect within 1 minute.
• The dashboard shows when each key was last used and the call log, including errors.
• If a key shows up in a public repository, revoke it and generate a new one immediately.

Scopes

Give each key only what it needs. Scopes for features that haven't shipped yet can be checked now: they take effect when the feature ships.

A call without the required scope gets a 403 with the code insufficient_scope.

Publishable keys

The publishable key identifies your account on the front end. It can only:

• load the agent widget;
• send visitor tracking events (/v1/collect).

It does not read conversations, contacts or metrics. Even so, you set which domains can use it in Dashboard → Developers → Widget in your app. Requests from other domains are rejected with 403 origin_not_allowed. There is one publishable key per environment; generating a new one disables the previous one immediately.

Session token

When the user is already logged in to your system, your server generates a session token and hands it to the front end. That way the widget knows who the person is without exposing the secret key.

curl https://api.nevox.ai/v1/widget/sessions \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_8f2k1x",
    "contact": {
      "external_id": "patient_1042",
      "name": "Mary Smith",
      "email": "mary@example.com",
      "language": "en-US"
    }
  }'

{
  "token": "nvx_st_9c1e...",
  "expires_at": "2026-11-03T15:30:00Z",
  "contact_id": "ctc_4hq81"
}

The token is valid for 1 hour and only for that contact and that agent. Generate a new one on every login or when it expires. See how to use it in the widget.

Environments