> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aventure.vc/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aventure.vc/_mcp/server.

# Authentication

The API, CLI, and MCP server all require an
[aVenture account](https://aventure.vc/sign-up); free and paid plans both work.
How you sign in depends on where you work:

| Where you work                                  | How you sign in                                                                                                                                                                     |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MCP client (Claude, ChatGPT, and other AI apps) | Sign in through the browser when your client connects; use OAuth discovery and automatic client registration. See the [MCP quickstart](/mcp) for the fallback client ID when needed |
| CLI                                             | Run `aventure auth login`, or set `AUTH_TOKEN` to an API key                                                                                                                        |
| Researchly                                      | Choose **Connect aVenture** under [Profile, then MCP servers](https://researchly.chat/profile/mcp-servers)                                                                          |
| API                                             | Send an API key as a bearer token                                                                                                                                                   |

## Create an API Key

1. Sign in to aVenture.
2. Open [API Keys settings](https://aventure.vc/settings/api-keys).
3. Choose **Add new key**.

Store the key in your secret manager and load it into the `AUTH_TOKEN`
environment variable at runtime. The same page lists and revokes your keys.
Send it on every request:

```bash
curl -H "Authorization: Bearer $AUTH_TOKEN" \
  "https://api.aventure.vc/v1/auth/me/permissions"
```

A `200` confirms the key works and lists what it can reach.

## Sign In From the CLI

```bash
aventure auth login
```

The command opens your browser for OAuth sign-in. For SSH, containers, or
another device, use:

```bash
aventure auth login --no-browser
```

When the issuer advertises OAuth device authorization, `--no-browser` uses
that flow: open the returned URL on your device, approve the displayed code,
and let the CLI finish verifying and storing its OAuth access. If device
authorization is unavailable, follow the reported error rather than assuming
a loopback callback will complete in a headless session.

`aventure auth login --key --no-browser` is a separate API-key approval
fallback. It is not required for OAuth device approval.
[Developer Access settings](https://aventure.vc/settings/developer) lists past
CLI sign-ins and revokes them. In CI, set `AUTH_TOKEN` to an API key instead.

## Connect an MCP Client

The [MCP quickstart](/mcp#choose-your-ai-app) has setup instructions and prompts
for your AI app, plus the server URL and automatic OAuth registration settings.
Your client signs you in through the browser when it connects.

## Keep Credentials Safe

Anyone holding an API key or token has the access it grants, and their calls
use your allowances. Keep credentials server-side, load them from a secret
manager, and never ship one in browser code or commit one to a repository.

## When Authentication Fails

A missing, expired, or unrecognized credential returns `401`, and its `detail`
says how to sign in:

| Where you work | Fix a `401`                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| MCP client     | Reconnect the server so your client signs you in again; in Claude Code, run `/mcp` and select `aventure` |
| CLI            | Run `aventure auth login`; `aventure auth doctor` names any other failed setup check                     |
| API            | Send a current API key from [API Keys settings](https://aventure.vc/settings/api-keys)                   |

A valid credential that lacks permission for an operation returns `403`; signing
in again does not change it. Both use the standard [error body](/errors).