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

### Environment Variables

Store your API key as an environment variable:

<CodeGroup>
  ```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"])
  ```
</CodeGroup>

## JWT Bearer Token Authentication

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

<Steps>
  <Step title="Start OAuth flow">
    Redirect the user to the Google OAuth endpoint:

    ```
    GET /auth/google/redirect
    ```
  </Step>

  <Step title="Handle callback">
    After authentication, Google redirects to your callback URL with a one-time code:

    ```
    GET /auth/google/callback
    ```
  </Step>

  <Step title="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"}'
    ```
  </Step>

  <Step title="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..."
    ```
  </Step>
</Steps>

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

* **Use environment variables** — Never hardcode API keys in source code.
* **Rotate keys regularly** — Rotate API keys at least every 90 days. See [API Keys](/introduction/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.