The AI Support Agent API uses two layers of authentication:
  1. Agent API key — proves which provider is calling. Server-side, on every request.
  2. Verified session — proves which customer has been identity-checked. Required for sensitive reads and all changes.

​
1. Agent API key

Send your key in the X-API-Key header, exactly like the rest of the partner API:
The key is scoped to your provider — you can only reach your own customers.
Agent access is a separate capability from the standard partner API. Your key must have the agent_api_access feature enabled before any /agent/* route works — otherwise the call returns 403 AI agent API access is not enabled for this account. Ask your kurnl contact to enable it for the key you’ll use with the AI.
The X-API-Key credential must only ever be used server-side (from your AI backend), never from a browser or client device.

​
2. Verified session (email or SMS one-time code)

Before the agent reveals account detail or makes a change, the caller must be verified. The agent triggers a one-time code to the customer’s email (default) or phone on file, asks the caller to read it back, and validates it. On success it receives a short-lived token to send as X-Verified-Session.
Pass "channel": "sms" on verify/issue to send the code by text instead of email. SMS is delivered via Twilio and is inert until configured — until then an SMS request returns 503 dependency_unconfigured. Email is always available.
1

Issue a code

The code is sent — never returned in the response. Read sent_to back to the caller so they know which inbox (or phone) to check. Use "channel": "sms" to text it instead; sent_to is then a masked phone like •••42.
2

Validate the code

3

Use the session

Send the token on every protected call for that customer:

​
Rules

  • The token lasts 15 minutes and is bound to one (provider, customer) pair — it cannot be reused for a different customer (401).
  • The code is 6 digits, valid for 10 minutes, with a small attempt limit. Repeated failures should trigger a human handoff (open a ticket — see Reference).
  • verify/issue is rate-limited to 10/min per key; re-issuing within the cooldown re-sends the existing code rather than generating a new one.

​
Which auth for which endpoint

Ticket creation is intentionally not verification-gated: a key escalation trigger is a caller the AI could not verify, and the AI must still be able to open a ticket for them.

​
Sandbox

Test against a sandbox provider + a scoped agent key first — no live billing or network writes. See Sandbox or ask your kurnl contact to provision one.