---
title: Authenticate
description: Authenticate to Agnic Wallet using browser OAuth or non-browser API token mode
---

# Authenticate

Authenticate to Agnic Wallet using either browser OAuth or token mode for headless agents. This skill handles authentication, session management, and token storage.

---

## Non-Browser Token Mode (Recommended for Agents)

Use an existing Agnic token without opening a browser:

```bash
npx agnic@latest --token <agnic_token> status
```

Or set an environment variable:

```bash
export AGNIC_TOKEN=<agnic_token>
npx agnic@latest status
```

`--token` takes precedence over `AGNIC_TOKEN`.

---

## Browser OAuth Command

```bash
npx agnic@latest auth login
```

---

## How It Works

1. The CLI starts a temporary local server on a random port
2. Opens your default browser to Agnic's OAuth consent screen
3. You sign in (email, Google, or wallet) and approve spending limits
4. The browser redirects back to `http://localhost:<port>/callback`
5. The CLI exchanges the authorization code for tokens and saves them locally

Wait for the CLI to print `Authenticated!` before proceeding.

---

## Check Status

Before authenticating, check if a session is already active:

```bash
npx agnic@latest status
```

Expected output when authenticated:

```
Wallet Status
Authenticated

Email:    user@example.com
Wallet:   0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
Expires:  2026-05-22 14:30:00 UTC
```

---

## Logout

To remove stored credentials:

```bash
npx agnic@latest auth logout
```

---

## Token Storage

Credentials are stored in `~/.agnic/config.json` with restricted permissions (`0600`). Tokens auto-refresh on 401 responses — no manual re-authentication needed until the refresh token expires (90 days).

---

## Error Handling

| Error | Solution |
|-------|----------|
| "Not authenticated" | Provide `--token`, set `AGNIC_TOKEN`, or run `npx agnic@latest auth login` |
| "Authentication failed" | User cancelled the browser flow or the timeout (5 min) expired |
| "Could not open browser" | The CLI prints a URL to copy and open manually |
| "Invalid or revoked token" | Token is incorrect, revoked, or expired; rotate and retry |
| "Token expired" | Tokens auto-refresh; if refresh also fails, re-run `npx agnic@latest auth login` |

---

## Next Steps

<Cards>
  <Card title="Check Balance" href="/docs/agentic-wallet/skills/check-balance">
    Check your USDC balance after authenticating
  </Card>
  <Card title="Skills Overview" href="/docs/agentic-wallet/skills">
    Browse all available skills
  </Card>
</Cards>