---
title: "Authentication — AVCodex Docs"
description: "Authentication — AVCodex documentation for AV integrators, programmers, and ops teams."
lang: en
json-ld:
---

[](/)

Solutions

[Pricing](/pricing)[The Signal](/blog)[Resources](/resources)

Learn

[Free AI Assessment](/scorecard)[Get Started →](/pricing)

[Documentation Home](/docs)

Guides 

Getting Started

-   [The Alchemist Copilot](/docs/guides/the-alchemist-copilot)
-   [Choosing a Model](/docs/guides/choosing-a-model)
-   [Skills & Templates](/docs/guides/skills-and-templates)
-   [Pricing & Usage](/docs/guides/pricing-and-usage)
-   [Understanding Tokens](/docs/guides/understanding-tokens)
-   [Maximize AVCodex Capabilities](/docs/guides/maximize-avcodex-capabilities)

Knowledge & Memory

-   [How Knowledge Sources Work](/docs/guides/how-knowledge-sources-work)
-   [Knowledge Retrieval Settings](/docs/guides/knowledge-retrieval-settings)
-   [User Memory](/docs/guides/user-memory)
-   [Consumer Brain](/docs/guides/consumer-brain)

Agent Capabilities

-   [Image Recognition](/docs/guides/image-recognition)
-   [Image Generation](/docs/guides/image-generation)
-   [Video Generation](/docs/guides/video-generation)
-   [Deep Research and Deep Thinking](/docs/guides/deep-research-and-deep-thinking)
-   [Heartbeat (Proactive AI Outreach)](/docs/guides/heartbeat-proactive-ai-outreach)
-   [Database Connections](/docs/guides/database-connections)
-   [Agent-to-Agent Links](/docs/guides/agent-to-agent-links)
-   [Message Tagging](/docs/guides/message-tagging)
-   [Lead Generation Forms](/docs/guides/lead-generation-forms)
-   [Multilingual Apps](/docs/guides/multilingual-apps)
-   [Understanding Evaluations](/docs/guides/understanding-evaluations)

Design & Experience

-   [Style Studio](/docs/guides/style-studio)
-   [Component Studio](/docs/guides/component-studio)
-   [HQ Profile](/docs/guides/hq-profile)
-   [Multiplayer Chat](/docs/guides/multiplayer-chat)
-   [Circles](/docs/guides/circles)
-   [Desktop Agent](/docs/guides/desktop-agent)

Voice & Phone

-   [Phone Numbers](/docs/guides/phone-numbers)
-   [Outbound Calling](/docs/guides/outbound-calling)
-   [Voice Cloning](/docs/guides/voice-cloning)

Publish & Share

-   [Embed Chat Widget](/docs/guides/embed-chat-widget)
-   [Custom Domains](/docs/guides/custom-domains)
-   [PWA Installation](/docs/guides/pwa-installation)
-   [AVCodex Sites](/docs/guides/avcodex-sites)
-   [Embed on Kajabi](/docs/guides/embed-on-kajabi)
-   [How to Use AVCodex with Claude Code](/docs/guides/how-to-use-avcodex-with-claude-code)

Monetization & Access

-   [Selling Access](/docs/guides/selling-access)
-   [Consumer Monetization](/docs/guides/consumer-monetization)
-   [Access Control](/docs/guides/access-control)
-   [Bring Your Own Auth](/docs/guides/bring-your-own-auth)
-   [Clever SSO for Schools](/docs/guides/clever-sso-for-schools)

Analytics & Operations

-   [Analytics & Chat History](/docs/guides/analytics-and-chat-history)
-   [Performance Dashboard](/docs/guides/performance-dashboard)
-   [Programmatic Usage Stats](/docs/guides/programmatic-usage-stats)
-   [Session Lifecycle Webhooks](/docs/guides/session-lifecycle-webhooks)
-   [Audit Logs](/docs/guides/audit-logs)

Teams & White-Label

-   [Team Management](/docs/guides/team-management)
-   [Enterprise Whitelabel](/docs/guides/enterprise-whitelabel)

Alchemist Platform

-   [Alchemist Tickets](/docs/guides/alchemist-tickets)
-   [Alchemist Getting Started](/docs/guides/alchemist-getting-started)
-   [Alchemist Working with Tickets](/docs/guides/alchemist-working-with-tickets)
-   [Alchemist Local Development](/docs/guides/alchemist-local-development)

Alchemist Operations

-   [Alchemist Environment Variables](/docs/guides/alchemist-environment-variables)
-   [Alchemist Deploys and Domains](/docs/guides/alchemist-deploys-and-domains)
-   [Alchemist Self-Healing](/docs/guides/alchemist-self-healing)

Alchemist API & Automation

-   [Alchemist API Keys](/docs/guides/alchemist-api-keys)
-   [Alchemist MCP Server](/docs/guides/alchemist-mcp-server)
-   [Alchemist Pipeline Configuration](/docs/guides/alchemist-pipeline-configuration)
-   [Alchemist Pipeline Permutations](/docs/guides/alchemist-pipeline-permutations)

Developer Platform

-   [Building Custom MCP Servers](/docs/guides/building-custom-mcp-servers)
-   [Consumer OAuth for Custom MCP Servers](/docs/guides/consumer-oauth-for-custom-mcp-servers)

AVCodex MCP Server

-   [Overview](/docs/guides/overview)
-   [MCP Reference](/docs/guides/mcp-reference)
-   [Setup & Installation](/docs/guides/setup-and-installation)
-   [Authentication](/docs/guides/authentication)
-   [Tools Reference](/docs/guides/tools-reference)
-   [Common Workflows](/docs/guides/common-workflows)
-   [Rate Limits](/docs/guides/rate-limits)

Custom Actions 

Pro Actions 

API 

Builder API 

Agentic Commerce (ACP) 

Integrations 

[Docs](/docs)/ Guides / AVCodex MCP Server 

# Authentication

Last updated · MAR 2026 · [Read as Markdown](/docs/guides/authentication.md)

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# ](#oauth-authentication)

### [How it works# ](#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# ](#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:

code 

```
Connected to AVCodex MCP Server
Available tools: list_apps, create_app, get_app_analytics...
```

### [Token management# ](#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# ](#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# ](#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# ](#key-format)

API keys use the `avcodex_sk_` prefix:

code 

```
avcodex_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v
```

### [Using API keys# ](#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# ](#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# ](#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-access)

### [Revoking OAuth tokens# ](#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# ](#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# ](#troubleshooting)

### ["Authentication required"# ](#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"# ](#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# ](#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"# ](#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# ](#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# ](#security-details)

For those interested in the technical implementation.

### [OAuth 2.0 with PKCE# ](#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# ](#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# ](#oauth-flow-reference)

For developers building custom MCP clients or debugging issues.

### [Endpoints# ](#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# ](#authorization-request)

code 

```
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# ](#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# ](#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# ](#next-steps)

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

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

Was this helpful? 

[Edit this page →](#)

[

Previous

Setup & Installation

](/docs/guides/setup-and-installation)[

Next

Tools Reference

](/docs/guides/tools-reference)

On this page

-   [OAuth authentication](#oauth-authentication)
-   [How it works](#how-it-works)
-   [What you'll see](#what-you-ll-see)
-   [Token management](#token-management)
-   [API keys](#api-keys)
-   [Creating an API key](#creating-an-api-key)
-   [Key format](#key-format)
-   [Using API keys](#using-api-keys)
-   [Key security](#key-security)
-   [Permission scopes](#permission-scopes)
-   [Revoking access](#revoking-access)
-   [Revoking OAuth tokens](#revoking-oauth-tokens)
-   [Revoking API keys](#revoking-api-keys)
-   [Troubleshooting](#troubleshooting)
-   ["Authentication required"](#authentication-required)
-   ["Scope not authorized"](#scope-not-authorized)
-   [Browser doesn't open](#browser-doesn-t-open)
-   ["Invalid token format"](#invalid-token-format)
-   [Connection times out](#connection-times-out)
-   [Security details](#security-details)
-   [OAuth 2.0 with PKCE](#oauth-2-0-with-pkce)
-   [Token storage](#token-storage)
-   [OAuth flow reference](#oauth-flow-reference)
-   [Endpoints](#endpoints)
-   [Authorization request](#authorization-request)
-   [Token exchange](#token-exchange)
-   [Token refresh](#token-refresh)
-   [Next steps](#next-steps)

[](/)

The AI platform built exclusively for professional AV. Build, deploy, and sell AI tools that understand your industry.

### Platform

-   What You Can Build
-   Templates
-   [Pricing](/pricing)

### Services

-   [Done-For-You](/pricing)
-   [Academy](/academy)
-   [Contact](/contact)

### Company

-   About
-   [The Signal](/blog)
-   [Docs](/docs)
-   [LinkedIn](#)

© 2026 AVCodex. A Future Ready Holdings Inc. product. SOC 2 Type II Certified · HIPAA Compliant