Authenticate with the Praxa Integration Gateway API

Praxa uses short-lived OAuth Bearer tokens to authenticate every request to the Integration Gateway. Tokens are delegated, meaning they are issued on behalf of a specific principal within your Praxa deployment, and scoped, meaning each token declares exactly which operations it may be used for. No provider API keys are ever passed to your application — authentication with the gateway is entirely separate from the server-side provider credentials Praxa manages on your behalf.

Getting Your Access Token

Access tokens are issued by your Praxa gateway deployment as short-lived OAuth tokens. Each token is bound to a specific gateway audience, tenant, principal, and set of scopes. The exact flow for obtaining a token — whether through an admin panel, a CLI tool, or a service account credential exchange — depends on how your Praxa deployment is configured. Contact your Praxa deployment administrator or refer to your gateway’s own documentation to learn how to request a token with the scopes your integration needs. Ask only for the scopes required by the operations you intend to call; the gateway enforces the declared scope for every operation.

Always use HTTPS when connecting to the Praxa Integration Gateway. The SDK rejects HTTP origins at construction time and will throw before making any network request. Never embed your access token in a URL — pass it only through the accessToken option or the PRAXA_ACCESS_TOKEN environment variable.

Using Your Token with the SDK

Pass your token through the accessToken option when constructing a PraxaClient. This option accepts a function that returns a string or a Promise<string>. Using an async function is strongly preferred in production because it lets your application refresh the token transparently without recreating the client. Local smoke test — environment-backed token:

import { PraxaClient } from "@praxa/sdk";

const accessToken = process.env.PRAXA_ACCESS_TOKEN;
if (!accessToken) throw new Error("PRAXA_ACCESS_TOKEN is required");

const client = new PraxaClient({
  baseUrl: "https://api.your-praxa-gateway.example",
  accessToken: () => accessToken,
});

Recommended — async token provider:

import { PraxaClient } from "@praxa/sdk";

const client = new PraxaClient({
  baseUrl: process.env.PRAXA_BASE_URL!,
  accessToken: async () => {
    // Retrieve a fresh token from your session or secret store.
    // This function is called before each authenticated request.
    return session.getPraxaAccessToken();
  },
});

The async provider pattern means your client remains valid across token expiry boundaries. The SDK calls your provider function before each request, so returning a refreshed token automatically keeps the client authenticated.

In production, always use an async token provider function that retrieves a fresh token from your session or secret store. This lets you integrate with your platform’s secret management layer and rotate tokens without restarting your application.

Using Your Token with the CLI

The @praxa/cli reads your gateway URL and token from environment variables. Set both before running any CLI command:

export PRAXA_BASE_URL="https://api.your-praxa-gateway.example"
export PRAXA_ACCESS_TOKEN="<your-short-lived-oauth-token>"

You can verify your configuration with the read-only doctor command:

praxa doctor

Use --base-url to override PRAXA_BASE_URL for a single command without changing your environment:

praxa doctor --base-url https://api.other-gateway.example

PRAXA_BASE_URL and PRAXA_ACCESS_TOKEN are the standard environment variables for all Praxa integrations.

OAuth Scopes

Every operation in the Praxa Integration Gateway API requires exactly one OAuth scope. Your access token must include the appropriate scope for every operation you call — the gateway rejects requests with missing or insufficient scopes with a 403 Forbidden response. Request only the scopes your integration actually needs. A scope authorises a request to reach server-side policy evaluation; it does not itself cause a provider effect.

Scope	Operations covered
`missions:write`	Submit intent, create a mission, signal a mission, cancel a mission
`missions:read`	Get a mission, stream mission events
`capabilities:read`	Search capabilities
`memory:read`	Query memory
`skills:read`	Get a skill
`traces:read`	Get a trace
`context:read`	List goals
`world:read`	List world model certificates
`coverage:read`	Get reference coverage
`mcp:invoke`	MCP 2025-11-25 Streamable HTTP JSON-RPC endpoint with negotiated 2025-03-26 compatibility

Auth Errors

The gateway returns standard HTTP error responses for authentication and authorisation failures: 401 Unauthorized — Your request did not include a valid Bearer token, the token has expired, or the token signature could not be verified against the gateway’s expected audience. Check that PRAXA_ACCESS_TOKEN is set, that the token has not expired, and that it was issued for the correct gateway audience. 403 Forbidden — Your token is valid and was verified, but it does not include the scope required by the operation you called. Request a new token that includes the needed scope, or adjust your integration to call only operations covered by your current token’s scopes.

Never send requests over plain HTTP. Even if a gateway host is reachable over HTTP, sending a Bearer token over an unencrypted connection exposes it to interception. The Praxa SDK enforces HTTPS at construction time, but double-check any raw HTTP client usage in your infrastructure.

Get started

Core Concepts

Releases

Authenticate with the Praxa Integration Gateway API

Getting Your Access Token

Using Your Token with the SDK

Using Your Token with the CLI

OAuth Scopes

Auth Errors

​Getting Your Access Token

​Using Your Token with the SDK

​Using Your Token with the CLI

​OAuth Scopes

​Auth Errors

Getting Your Access Token

Using Your Token with the SDK

Using Your Token with the CLI

OAuth Scopes

Auth Errors