# Authentication

All Aigon integrations — REST API, CLI, and MCP — require authentication. There are two types of token:

| Type | Lifetime | Used by |
|------|----------|---------|
| **API token** | Permanent — never expires, no refresh | CLI, REST API |
| **OAuth access token** | Short-lived (~1 hour), auto-refreshed | MCP Server |

API tokens are obtained from the Telegram Auth Bot or the AigonOne web app. OAuth tokens are issued automatically during the browser consent flow.

---

## Telegram Auth Bot {#telegram}

The simplest way to get an API token. No prior account needed — your Telegram identity is your credential.

1. Open [t.me/aigon_auth_bot](https://t.me/aigon_auth_bot)
2. Send `/get`
3. Copy the token

**Commands:**

| Command | What it does |
|---------|-------------|
| `/get` | Returns your current token (creates one if you don't have one) |
| `/revoke` | Invalidates the current token and issues a new one |

---

## AigonOne Web App {#web}

If you're already signed in to [a1.aigon.ai](https://a1.aigon.ai), you can get your token from the web interface:

1. Click your profile icon (top right)
2. Select **API Token**
3. Copy the displayed token

From this screen you can also regenerate or delete your token.

---

## OAuth {#oauth}

The REST API (`api.aigon.ai`) implements a full OAuth 2.1 authorization server. The AigonOne web app (`a1.aigon.ai`) acts as the browser-facing rendering proxy — it handles login and consent UI, but all OAuth logic and state lives in the REST API.

This is used by the [MCP Server](/docs/mcp/). When an MCP client first connects, it opens a browser window for login and consent — no manual token handling required. Every MCP consumer (Claude Code, Claude Desktop, or any other MCP-compatible client) runs the same flow.

### How it works

1. The MCP client discovers the OAuth metadata from `a1.aigon.ai`
2. It registers dynamically with `api.aigon.ai/oauth/register`
3. A browser window opens at `a1.aigon.ai/oauth/authorize` for login + consent
4. A1 proxies the authorization to `api.aigon.ai`, which issues the code
5. The client exchanges the code for tokens at `api.aigon.ai/oauth/token`

### Endpoints

| Endpoint | Host | Purpose |
|----------|------|---------|
| `/.well-known/oauth-authorization-server` | a1.aigon.ai | Metadata discovery |
| `/oauth/authorize` | a1.aigon.ai | Browser login + consent |
| `/oauth/register` | api.aigon.ai | Dynamic client registration |
| `/oauth/token` | api.aigon.ai | Token exchange |
| `/oauth/revoke` | api.aigon.ai | Token revocation |

### Standards

- OAuth 2.1 with Authorization Code + PKCE ([RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636))
- Dynamic client registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591))
- Authorization server metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414))
- Access tokens are short-lived (~1 hour), refresh tokens ~30 days

---

## Using Your Token

Once you have a token, use it as a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_TOKEN
```

### CLI

```bash
aigon config set api.token YOUR_TOKEN
```

### REST API

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.aigon.ai/health
```

### MCP Server

OAuth handles this automatically — no manual token configuration needed.