> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentwallex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the AgentWallex API using API keys or JWT tokens.

## 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.

```bash theme={null}
curl -X GET https://api.agentwallex.com/api/v1/agents \
  -H "X-API-Key: awx_your_api_key"
```

> [!WARNING]
>
> 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:

```bash .env theme={null}
AGENTWALLEX_API_KEY=awx_your_api_key
```

```typescript TypeScript theme={null}
import { AgentWallex } from "@agentwallex/sdk";

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

```python Python theme={null}
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:

**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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOi..."
```

## Security Best Practices

> [!TIP]
>
> 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](https://docs.agentwallex.com/introduction/api-keys.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.