Skip to main content

​
Authentication Methods

AgentWallex supports two authentication methods:
MethodHeaderUse Case
API KeyX-API-Key: awx_...SDK and server-to-server integrations
JWT Bearer TokenAuthorization: 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

​
JWT Bearer Token Authentication

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

Start OAuth flow

Redirect the user to the Google OAuth endpoint:
GET /auth/google/redirect
2

Handle callback

After authentication, Google redirects to your callback URL with a one-time code:
GET /auth/google/callback
3

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"}'
4

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.