Authentication

Authentication Methods

AgentWallex supports two authentication methods:

Method	Header	Use Case
API Key	`X-API-Key: awx_...`	SDK and server-to-server integrations
JWT Bearer Token	`Authorization: Bearer eyJ...`	Web app, OAuth, and dashboard sessions

API Key Authentication

API keys are the recommended approach for server-side and SDK integrations. Every key starts with the awx_ prefix.

curl -X GET https://api.agentwallex.com/api/v1/agents \
  -H "X-API-Key: awx_your_api_key"

Never expose your API key in client-side code, public repositories, or logs. Always load it from environment variables.

Environment Variables

Store your API key as an environment variable:

AGENTWALLEX_API_KEY=awx_your_api_key

import { AgentWallex } from "@agentwallex/sdk";

const aw = new AgentWallex({
  apiKey: process.env.AGENTWALLEX_API_KEY!,
});

import os
from agentwallex import AgentWallex

aw = AgentWallex(api_key=os.environ["AGENTWALLEX_API_KEY"])

JWT Bearer Token Authentication

For web applications and OAuth flows, use JWT bearer tokens. Tokens are obtained through the Google OAuth flow:

Start OAuth flow

Redirect the user to the Google OAuth endpoint:

GET /auth/google/redirect

Handle callback

After authentication, Google redirects to your callback URL with a one-time code:

GET /auth/google/callback

Exchange for tokens

Exchange the one-time code for access and refresh tokens:

curl -X POST https://api.agentwallex.com/api/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{"exchange_code": "one_time_code"}'

Use the access token

Include the access token in the Authorization header:

curl -X GET https://api.agentwallex.com/api/v1/agents \
  -H "Authorization: Bearer eyJhbGciOi..."

Refreshing Tokens

Access tokens expire. Use the refresh token to obtain a new access token:

curl -X POST https://api.agentwallex.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your_refresh_token"}'

Logout

Invalidate the current session:

curl -X POST https://api.agentwallex.com/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOi..."

Security Best Practices

Follow these practices to keep your integration secure.

Use environment variables — Never hardcode API keys in source code.
Rotate keys regularly — Rotate API keys at least every 90 days. See API Keys for rotation instructions.
Use the minimum scope needed — Create separate API keys per environment (sandbox vs. production).
Enable IP allowlisting — Available on Growth and Enterprise plans to restrict API access to known IPs.
Monitor audit logs — Review authentication events in the dashboard or via GET /audit-logs.
Use sandbox for development — Never test with production keys or real funds.

Getting Started

Platform

Core Features

Guides

Authentication Methods

API Key Authentication

Environment Variables

JWT Bearer Token Authentication

Refreshing Tokens

Logout

Security Best Practices

​Authentication Methods

​API Key Authentication

​Environment Variables

​JWT Bearer Token Authentication

​Refreshing Tokens

​Logout

​Security Best Practices

Authentication Methods

API Key Authentication

Environment Variables

JWT Bearer Token Authentication

Refreshing Tokens

Logout

Security Best Practices