Auth & Connection

​

Open the Connect modal

​

What’s in the modal, and where to use each value

​

Which key for which route

• Your backend, with the service role key. Send the key as both apikey and Authorization: Bearer. Every /api/* route accepts it. The Studio calls the API the same way.
• A signed-in end user, with their own access token. Send the Anon key as apikey and the user’s access token (the JWT your project’s Auth service returned at sign-in) as Authorization: Bearer. Only the 16 conversation routes below accept it, and only for that user’s own sessions and runs.

{"error": "This endpoint requires the project's service role key"}

​

End-user routes

​

Rules for end-user runs

• The token must name the user and expire. The API accepts a JWT with audience authenticated, signed with your project’s JWT secret, whose sub is a UUID and which carries an exp. Anything else answers 401. Tokens from your project’s Auth service always qualify; this matters only if you mint your own.
• The run uses the agent’s own knowledge bases. An end user’s run body may not set knowledge_bases, runtime_knowledge_bases, context_handler_id, or by-reference context_items (items with an item_id). Sending any of them answers 403 with a body that names the fields:
  {"error": "knowledge_bases may only be set with the project's service role key; an end user's run uses the knowledge bases configured on the agent"}
  
  context_override and by-value context_items (items with text) are still allowed, because the user supplies that text themselves.
• An end user can continue only their own existing session, and can never name a new one. A session_id in a run body or a path must be a string of at most 255 characters, or the request answers 400. A run continues a session only if it already exists and belongs to the caller, for the same agent or orchestration; any other session_id answers 404 (a streamed run ends with the event {"event": "error", "error": "Session not found"}). To start a conversation, omit session_id (the run creates a session owned by the user and returns its id) or call POST /api/agents/{agent_id}/sessions. This stops a user from creating a session under an id your backend would later pick, such as one derived from a phone number, and reading or steering what your backend’s runs say in it.
• An end user approves only the paused runs they started. A run your backend started with the service role key has no end-user owner, even in a session created with that user’s user_id, so only the service role key can approve it. Relay the user’s decision from your backend.

​

Running agents for a user from your backend

​

What agent data tools act as

​

Migrating from earlier versions

• If your backend forwarded an end-user JWT to knowledge-base or source routes (or any other route outside the table above), switch those calls to the service role key.
• If your client sent knowledge_bases on a run (or runtime_knowledge_bases, context_handler_id, or by-reference context_items), configure the knowledge bases on the agent instead with POST /api/agents/{id}/knowledge-bases. If the choice has to be made per request, run the agent from your backend with the service role key and pass user_id when you create the session.
• If your clients started sessions under ids they chose, have them omit session_id on the first run or call POST /api/agents/{agent_id}/sessions, and use the id that comes back.
• If you mint your own user JWTs, give them a UUID sub and an exp.
• If you self-host, set SERVICE_ROLE_KEY on the API service. Without it no caller counts as the service role: a request that bears the service role key is decoded as an end-user token and answers 401, and every management route is unreachable.
• If an agent has database tools, check its configured tables. They must be plain or partitioned tables or views created WITH (security_invoker = true), and service-role runs now reach exactly those tables and nothing else.

​

Use it from code

import requests

BASE_URL = "{BASE_URL}"   # Connect modal -> Project URL
API_KEY = "{API_KEY}"     # Connect modal -> Service Role (Secret) Key

headers = {
    "apikey": API_KEY,
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

const BASE_URL = "{BASE_URL}";  // Connect modal -> Project URL
const API_KEY = "{API_KEY}";    // Connect modal -> Service Role (Secret) Key

const headers = {
  apikey: API_KEY,
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

# BASE_URL -> Project URL from the Connect modal
# API_KEY  -> Service Role (Secret) Key from the Connect modal
-H "apikey: {API_KEY}" \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json"

response = requests.get(
    f"{BASE_URL}/api/agents",
    headers=headers,
)
print(response.json())

const response = await fetch(`${BASE_URL}/api/agents`, { headers });
const agents = await response.json();
console.log(agents);

curl '{BASE_URL}/api/agents' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}"

{
  "agents": [
    {
      "id": "uuid-here",
      "name": "My Agent",
      "model": "gpt-4o",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

# Python (psycopg2) — from Connection Strings -> Python
import psycopg2

conn = psycopg2.connect("{POSTGRES_URL}")  # Database URL from the Connect modal
with conn.cursor() as cur:
    cur.execute("select count(*) from public.users")
    print(cur.fetchone())

// Node.js (pg) — from Connection Strings -> Node.js
import { Client } from "pg";

const client = new Client({ connectionString: "{POSTGRES_URL}" });  // Database URL
await client.connect();
const { rows } = await client.query("select count(*) from public.users");
console.log(rows);

# psql — from Connection Strings -> PSQL
psql "{POSTGRES_URL}"

​

What’s Next