# Authentication

How authentication works when connecting MCP clients to your AVCodex account.

---

The AVCodex MCP Server supports two authentication methods: **OAuth 2.0 with PKCE** (for interactive MCP clients) and **API Keys** (for automation, CI pipelines, and scripts). This page covers both and how to troubleshoot common issues.

## OAuth authentication

### How it works

> **Note:** You don't need to write any code. Your MCP client handles the OAuth flow automatically.

When you first use an AVCodex MCP tool:

1. **Your MCP client opens a browser window** to the AVCodex authorization page.
2. **You log in with your AVCodex account** (or you're already logged in).
3. **You approve the connection** by clicking "Authorize".
4. **The browser closes** and your MCP client is now connected.

That's it. Your client stores the tokens securely and refreshes them automatically.

### What you'll see

#### Authorization screen

When prompted to authorize, you'll see:
- **AVCodex MCP Server** as the application requesting access.
- **Your AVCodex account email** to confirm you're logged in.
- **Requested permissions** (typically full access to your agents).
- **Authorize** and **Deny** buttons.

#### After authorization

Your MCP client will confirm the connection. In Claude Code, you might see:
```
Connected to AVCodex MCP Server
Available tools: list_apps, create_app, get_app_analytics...
```

### Token management

AVCodex uses prefixed tokens that your MCP client manages automatically:

| Token type | Prefix | Lifetime | What it does |
|------------|--------|----------|--------------|
| Access token | `avcodex_at_` | 1 hour | Authenticates each request |
| Refresh token | `avcodex_rt_` | 30 days | Gets new access tokens when they expire |

Your MCP client:
- Stores tokens securely in its configuration.
- Automatically refreshes expired access tokens.
- Prompts you to re-authorize if the refresh token expires.

---

## API keys

For automation, CI/CD pipelines, and scripts, API keys provide non-interactive auth without the browser flow. Useful when an integration server overnight pulls fresh manufacturer firmware notes into an agent's knowledge base, or when a build script regenerates client-specific support agents.

### Creating an API key

1. Go to **Settings, Developer, API Keys** in your AVCodex dashboard.
2. Click **Create Key** and give it a descriptive name.
3. Optionally select specific permission scopes (or leave full access).
4. Optionally set an expiration (30 days, 90 days, 1 year, or never).
5. Copy the key immediately. It is shown only once.

### Key format

API keys use the `avcodex_sk_` prefix:

```
avcodex_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v
```

### Using API keys

Pass the API key as a Bearer token:

```json
{
  "mcpServers": {
    "avcodex": {
      "url": "https://app.avcodex.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer avcodex_sk_xxxxx"
      }
    }
  }
}
```

Or in direct HTTP requests:

```bash
curl -X POST https://app.avcodex.com/mcp \
  -H "Authorization: Bearer avcodex_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```

### Key security

- **Keys are hashed in the database.** We cannot retrieve your key after creation.
- **Keys can be scoped** to specific permissions (read-only, for example).
- **Keys never expire by default.** Optionally set 30-day, 90-day, or 1-year expiration.
- **Keys can be revoked instantly** from the Developer settings page.

> **Warning:** Treat API keys like passwords. Never commit them to source control or share them in plaintext. Use environment variables or a secret manager.

---

## Permission scopes

Both OAuth tokens and API keys use the same permission scopes:

| Scope | What it allows |
|-------|----------------|
| `apps:read` | View your agents |
| `apps:write` | Create, update, delete agents |
| `knowledge:read` | View knowledge sources |
| `knowledge:write` | Add, update, delete knowledge sources |
| `actions:read` | View custom actions |
| `actions:write` | Manage custom actions |
| `analytics:read` | View conversation analytics |
| `workspace:read` | View workspace information |
| `workspace:write` | Create and update workspaces |
| `billing:read` | View subscription and credits |
| `*` | All permissions |

---

## Revoking access

### Revoking OAuth tokens

To disconnect an MCP client from your AVCodex account, revoke your tokens programmatically:

```bash
# Revoke your refresh token
curl -X POST https://app.avcodex.com/mcp/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "avcodex_rt_your_refresh_token", "token_type_hint": "refresh_token"}'
```

For Claude Code, you can also clear stored credentials to force re-authorization:

```bash
# Remove stored AVCodex OAuth tokens
rm -rf ~/.claude/mcp-auth/avcodex*
```

### Revoking API keys

Go to **Settings, Developer, API Keys** in your AVCodex dashboard and click **Delete** next to the key you want to revoke. The key is deactivated immediately.

After revoking or clearing credentials, your MCP client will prompt you to re-authorize the next time you use an AVCodex tool.

---

## Troubleshooting

### "Authentication required"

**What happened:** Your token expired and couldn't be refreshed.

**Fix:** Your MCP client should automatically prompt you to re-authorize. If not:
1. Restart your MCP client (for example, restart Claude Code).
2. Try using an AVCodex tool again to trigger the auth flow.

### "Scope not authorized"

**What happened:** The tool requires a permission that wasn't granted.

**Fix:** Re-authorize with broader permissions. Most MCP clients request all scopes automatically, so this is rare.

### Browser doesn't open

**What happened:** The auth flow couldn't open your default browser.

**Fix:**
1. Check if your MCP client logged a URL you can copy and paste.
2. Ensure a default browser is configured on your system.
3. Try restarting your MCP client.

### "Invalid token format"

**What happened:** The stored token is corrupted or incomplete.

**Fix:**
1. Clear your MCP client's stored AVCodex credentials.
2. Re-authorize from scratch.

For Claude Code, reset credentials:
```bash
# Remove stored AVCodex OAuth tokens
rm -rf ~/.claude/mcp-auth/avcodex*
```

### Connection times out

**What happened:** The authorization flow didn't complete in time.

**Fix:**
1. Complete browser authorization within 5 minutes.
2. Check your internet connection.
3. Try again. The flow is quick once you know what to expect.

---

## Security details

For those interested in the technical implementation.

### OAuth 2.0 with PKCE

The AVCodex MCP Server uses [OAuth 2.0 Authorization Code Flow with PKCE](https://oauth.net/2/pkce/):

- **PKCE (Proof Key for Code Exchange)** prevents authorization code interception.
- **S256 challenge method required.** Plain method is not supported.
- **No client secret required.** Safe for desktop applications.
- **Short-lived access tokens.** Minimize exposure if compromised.
- **Refresh token rotation.** Each refresh immediately revokes the previous access token and refresh token, and issues a new pair. Store the new tokens before discarding the response.

### Token storage

Your MCP client stores tokens securely:
- **Claude Code.** Encrypted in `~/.claude/` directory.
- **Cursor.** Stored in application settings.
- **Custom clients.** Should use the OS keychain or encrypted storage.

---

## OAuth flow reference

For developers building custom MCP clients or debugging issues.

### Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `https://app.avcodex.com/mcp/oauth/authorize` | GET | Start authorization |
| `https://app.avcodex.com/mcp/oauth/token` | POST | Exchange code for tokens |
| `https://app.avcodex.com/mcp/oauth/register` | POST | Dynamic client registration |
| `https://app.avcodex.com/mcp/oauth/revoke` | POST | Revoke tokens |
| `https://app.avcodex.com/.well-known/oauth-authorization-server` | GET | OAuth discovery |

### Authorization request

```
GET https://app.avcodex.com/mcp/oauth/authorize?
  client_id=avcodex_mcp_cli
  &redirect_uri=http://localhost:PORT/callback
  &response_type=code
  &scope=*
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256
```

### Token exchange

```bash
POST https://app.avcodex.com/mcp/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "redirect_uri": "http://localhost:PORT/callback",
  "client_id": "avcodex_mcp_cli",
  "code_verifier": "PKCE_VERIFIER"
}
```

### Token refresh

```bash
POST https://app.avcodex.com/mcp/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "avcodex_rt_xxx",
  "client_id": "avcodex_mcp_cli"
}
```

---

## Next steps

- Rate Limits. Understanding request limits.
- Tools Reference. All available tools.
- Common Workflows. Practical examples.

*AVCodex · Your AV expertise. Amplified by AI.*