Auth

AgentFlowClient supports three authentication strategies, all configured via the auth field in AgentFlowConfig. It also provides a legacy authToken shortcut for the common bearer-token case.

Source: src/request.ts

Import

import {
  AgentFlowClient,
  AgentFlowAuth,
  AgentFlowBearerAuth,
  AgentFlowBasicAuth,
  AgentFlowHeaderAuth,
} from '@10xscale/agentflow-client';

AgentFlowAuth union type

type AgentFlowAuth =
  | AgentFlowBearerAuth
  | AgentFlowBasicAuth
  | AgentFlowHeaderAuth;

Pass a value of this type to AgentFlowConfig.auth. If both authToken and auth are set, auth takes precedence.

Bearer token auth

AgentFlowBearerAuth

interface AgentFlowBearerAuth {
  type: 'bearer';
  token: string;
}

Adds the header:

Authorization: Bearer <token>

This is the dominant auth method when the server is configured with "auth": "jwt" or a custom BaseAuth that reads the Authorization: Bearer header.

Example

const client = new AgentFlowClient({
  baseUrl: 'http://localhost:8000',
  auth: {
    type: 'bearer',
    token: process.env.API_TOKEN!,
  },
});

Shorthand

For bearer tokens you can also use the authToken convenience field:

const client = new AgentFlowClient({
  baseUrl: 'http://localhost:8000',
  authToken: process.env.API_TOKEN,
});

Both examples produce the same Authorization header. Use auth: { type: 'bearer', token } when you want to keep all auth logic in one place.

Basic auth

AgentFlowBasicAuth

interface AgentFlowBasicAuth {
  type: 'basic';
  username: string;
  password: string;
}

Adds the header:

Authorization: Basic <base64(username:password)>

The encoding uses btoa() in browsers and Buffer.from() in Node.js.

Example

const client = new AgentFlowClient({
  baseUrl: 'http://localhost:8000',
  auth: {
    type: 'basic',
    username: 'admin',
    password: process.env.ADMIN_PASSWORD!,
  },
});

Custom header auth

AgentFlowHeaderAuth

interface AgentFlowHeaderAuth {
  type: 'header';
  name: string;     // Header name, e.g. 'X-API-Key'
  value: string;    // Header value
  prefix?: string | null;  // Optional prefix prepended to the value, e.g. 'ApiKey'
}

Sends a custom header with the specified name and value. If prefix is set, the header value is <prefix> <value>.

Example: API key header

const client = new AgentFlowClient({
  baseUrl: 'http://localhost:8000',
  auth: {
    type: 'header',
    name: 'X-API-Key',
    value: process.env.API_KEY!,
  },
});
// Sends: X-API-Key: <API_KEY>

Example: with prefix

const client = new AgentFlowClient({
  baseUrl: 'http://localhost:8000',
  auth: {
    type: 'header',
    name: 'Authorization',
    value: process.env.API_KEY!,
    prefix: 'ApiKey',
  },
});
// Sends: Authorization: ApiKey <API_KEY>

No auth

When the server is configured with "auth": null (no auth / open endpoint), omit auth and authToken entirely:

const client = new AgentFlowClient({
  baseUrl: 'http://localhost:8000',
  // No auth fields — appropriate for local development or
  // internal services behind a gateway
});

Additional headers

All three auth strategies can be combined with headers for custom per-request headers such as tracing IDs or gateway credentials:

const client = new AgentFlowClient({
  baseUrl: 'http://localhost:8000',
  auth: { type: 'bearer', token: process.env.TOKEN! },
  headers: {
    'X-Request-Source': 'web-app',
    'X-Tenant-ID': 'tenant-abc',
  },
});

The headers map is merged with the auth header and any content-type headers on every request. If a key in headers conflicts with a key set by auth, the auth value wins.

Auth header precedence

When both authToken and auth are provided, auth takes precedence. When headers contains an Authorization key and auth also sets Authorization, the auth value wins.

WebSocket authentication

Browsers cannot set request headers on a WebSocket, so the client sends the bearer token as a WebSocket subprotocol: the socket is opened with ['agentflow-bearer', '<token>'] and the server reads the second entry. The token is never placed in the URL. On Node runtimes whose WebSocket constructor accepts an options argument, an Authorization: Bearer ... header is passed as well.

wsStream() and realtime() do this for you. The pieces are also exported, for building your own socket against the same server:

import {
  buildWsUrl,
  openWebSocket,
  resolveBearerToken,
  WS_BEARER_SUBPROTOCOL,
} from '@10xscale/agentflow-client';

const context = {
  baseUrl: 'https://api.example.com',
  authToken: process.env.API_TOKEN,
};

resolveBearerToken(context);                     // the token, or null
buildWsUrl(context, '/v1/graph/ws');             // 'wss://api.example.com/v1/graph/ws'

const socket = openWebSocket(buildWsUrl(context, '/v1/graph/ws'), context);
// equivalent to: new WebSocket(url, [WS_BEARER_SUBPROTOCOL, token])

If a reverse proxy in front of your API strips Sec-WebSocket-Protocol, the handshake arrives unauthenticated and is rejected. Configure the proxy to forward it.

Matching client auth to server auth configuration

Use the following table to choose the right client-side auth type based on the auth field in 10xgraph.json:

See the server-side auth documentation at reference/api-cli/auth for how to generate JWT tokens and implement custom auth handlers.

Obtaining a JWT token

When the server is configured with "auth": "jwt", obtain a signed token with PyJWT on the server side and pass it to the client:

# Python: generate a test token
import jwt, os, datetime

token = jwt.encode(
    {
        "sub": "user-123",
        "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=24),
    },
    os.environ["JWT_SECRET_KEY"],
    algorithm=os.environ.get("JWT_ALGORITHM", "HS256"),
)
print(token)

// TypeScript: use the token
const client = new AgentFlowClient({
  baseUrl: 'http://localhost:8000',
  auth: {
    type: 'bearer',
    token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  },
});

Cookie credentials

For browser apps that rely on session cookies (e.g. an API gateway that sets a cookie), configure credentials:

const client = new AgentFlowClient({
  baseUrl: 'https://api.example.com',
  credentials: 'include',
  // No auth field — the cookie is sent automatically by the browser
});

credentials is forwarded directly to the fetch call. Valid values are 'omit', 'same-origin', and 'include'.

Common errors

What you learned

• Use auth: { type: 'bearer', token } for JWT auth (the most common case).
• Use auth: { type: 'header', name, value } for API-key header auth.
• Use auth: { type: 'basic', username, password } for HTTP Basic auth.
• Omit auth entirely for open/no-auth servers.
• credentials controls cookie handling in browser environments.
• WebSocket routes authenticate with the agentflow-bearer subprotocol, never a URL parameter, and resolve authToken before auth — the reverse of HTTP.

Next step

See Register remote tools to learn how to register client-side tools that the agent can invoke remotely.