Client tokens

2 endpoint-uri. Fiecare cale de mai jos este relativă la URL-ul de bază al API-ului și include deja prefixul /api/v1 — vezi convențiile pentru autentificare, paginare, erori și idempotență.

	Endpoint
POST	`/client-tokens`	Exchange a public key for a short-lived client token bound to an origin, assistant and session
POST	`/client-tokens/verify`	Verify a client token and return its claims. Useful for SDK development and for the gateway

Endpoint-uri

Exchange a public key for a short-lived client token bound to an origin, assistant and session

POST/client-tokens

The Origin header is checked against the key's allowed origins; a request from an origin the key does not name is refused even with a valid key.

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
The Origin header is checked, not a body field. A missing CREDENTIAL_ENCRYPTION_KEY is also surfaced as a 403 authentication_error rather than a 500.

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`public_key`	string	da	max 128 chars
`assistant_id`	string \| null	—
`user_id`	string \| null	—	max 128 chars
`session_id`	string \| null	—	max 64 chars
`ttl`	integer \| null	—	min 60. max 3600

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/client-tokens" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "public_key": "string",
       "assistant_id": "01JQ0000000000000000000000",
       "user_id": "01JQ0000000000000000000000",
       "session_id": "01JQ0000000000000000000000",
       "ttl": 1
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/client-tokens`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "public_key": "string",
    "assistant_id": "01JQ0000000000000000000000",
    "user_id": "01JQ0000000000000000000000",
    "session_id": "01JQ0000000000000000000000",
    "ttl": 1
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/client-tokens');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'public_key' => 'string',
    'assistant_id' => '01JQ0000000000000000000000',
    'user_id' => '01JQ0000000000000000000000',
    'session_id' => '01JQ0000000000000000000000',
    'ttl' => 1,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/client-tokens",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "public_key": "string",
      "assistant_id": "01JQ0000000000000000000000",
      "user_id": "01JQ0000000000000000000000",
      "session_id": "01JQ0000000000000000000000",
      "ttl": 1
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`201`	`data`-wrapped object

Erori

Status	Când apare
`403`	Unknown/inactive public key, disallowed origin or assistant, or inactive organization
`422`	Validation failed on public_key, assistant_id, session_id or ttl

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "token": "string",
    "token_type": "string",
    "expires_at": "2026-01-01T12:00:00+00:00",
    "expires_in": {},
    "organization_id": null,
    "assistant_id": null,
    "session_id": null
  }
}

Verify a client token and return its claims. Useful for SDK development and for the gateway

POST/client-tokens/verify

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
An invalid token is answered by the handler itself with 401 plus error.code (wrong_audience, wrong_origin, key_revoked, expired) — not by the global auth middleware.