Skip to main content
The Agntix gateway supports two authentication methods. You’ll use one or the other depending on who is making the call.
MethodHeaderWhen to use
API Keyx-api-key: pk_live_…Server-to-server, scripts, backend integrations
Bearer JWTAuthorization: Bearer <token>First-party browser apps that already have a Clerk session
All Agntix APIs are served from a single base URL behind the API gateway: 
https://api.agntix.ai
The gateway routes traffic to the appropriate upstream service based on the path prefix. As a customer you only ever talk to api.agntix.ai — internal service URLs are not exposed. API keys are scoped to an organization and may be limited to specific features (read-only, voice-only, etc.) at creation time.

​
Create

Open Settings → API Keys in the dashboard and click Create key. Pick a name, the scopes you want, then copy the value. The key is shown once. You can also create keys programmatically: 
curl https://api.agntix.ai/v1/chat/api-keys \
  -H "x-api-key: $AGNTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CI/CD bot", "scopes": ["chat:write", "agents:read"] }'

​
Use

Pass the key in the x-api-key header on every request: 
curl https://api.agntix.ai/v1/chat/agents \
  -H "x-api-key: $AGNTIX_API_KEY"

​
Rotate

Keys do not expire, but you can rotate at any time:
  1. Create a new key with the same scopes.
  2. Roll your service over to the new key.
  3. Delete the old key from the dashboard — the deletion is effective immediately.
Never embed an API key in a browser, mobile app, or anywhere a customer can read it. Use a short-lived Bearer JWT instead (below) or proxy through your own backend.

​
Method 2 — Bearer JWT (Clerk session)

If you’re building a first-party dashboard and the user is already signed in with Clerk, send their session JWT instead of an API key: 
curl https://api.agntix.ai/v1/chat/agents \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…"
The gateway validates the JWT against Clerk’s JWKS, attaches the user’s organization to the request context, and applies the same RBAC rules as if you’d called with an org API key.

​
Getting a JWT in the browser

If you’re using the official Clerk SDK: 
import { useAuth } from "@clerk/nextjs";

const { getToken } = useAuth();
const token = await getToken({ template: "agntix" }); // or your default template

fetch("https://api.agntix.ai/v1/chat/agents", {
  headers: { Authorization: `Bearer ${token}` },
});

​
Permissions & errors

StatusMeaning
200/201Authenticated and authorized
401 UnauthorizedMissing or invalid auth header
403 ForbiddenAuthenticated, but the key/JWT lacks the required permission
See the full list on the error codes page.

​
Security best practices

Rotate keys quarterly

Use the dashboard’s bulk rotation tool, or wire CI/CD to do it on a schedule.

Scope down

Issue a separate key per service with only the features it actually needs.

Use Bearer JWTs in the browser

Browser code never holds a long-lived API key.

Monitor usage

The dashboard’s API Keys page shows last-used timestamp per key — purge stale ones.