> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veromerchants.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How the Vero MCP Server authenticates users with OAuth 2.0 and Auth0

The Vero MCP Server uses **OAuth 2.0 Authorization Code** flow with **Auth0** as the identity provider. MCP clients that support OAuth handle this automatically — users just log in when prompted.

***

## How authentication works

**1. Client requests /mcp**

The MCP client sends an initial request to `/mcp` without a token. The server responds with `401 Unauthorized` and a `WWW-Authenticate` header containing a link to the protected resource metadata.

```http theme={null}
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://mcp.veromerchants.com/.well-known/oauth-protected-resource"
```

**2. Client discovers OAuth metadata**

The client fetches the protected resource metadata (RFC 9728), which points to the authorization server. It then fetches the authorization server metadata (RFC 8414) to learn the OAuth endpoints.

**3. Dynamic client registration**

The client registers itself via the `/oauth/register` endpoint (RFC 7591) and receives a `client_id`.

**4. User authorizes**

The client redirects the user to `/oauth/authorize`, which proxies to Auth0's authorization endpoint. The user logs in (or signs up) and grants access. Auth0 redirects back with an authorization code.

**5. Token exchange**

The client sends the authorization code to `/oauth/token`, which proxies to Auth0's token endpoint and injects the client secret. The client receives an access token.

**6. Authenticated requests**

All subsequent requests to `/mcp` include the access token as a Bearer token. The server validates it and forwards it to the Vero API.

***

## OAuth endpoints

The server implements the following OAuth-related endpoints:

| Endpoint | RFC | Purpose |
| - | - | - |
| `/.well-known/oauth-protected-resource` | [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) | Protected Resource Metadata — tells the client where to find the authorization server |
| `/.well-known/oauth-authorization-server` | [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) | Authorization Server Metadata — lists supported endpoints, scopes, and grant types |
| `/oauth/register` | [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) | Dynamic Client Registration — returns the pre-configured `client_id` |
| `/oauth/authorize` | | Authorization proxy — injects OIDC scopes and redirects to Auth0 |
| `/oauth/callback` | | Callback proxy — forwards the authorization code to the MCP client |
| `/oauth/token` | | Token proxy — injects the client secret and forwards to Auth0 |

***

## Token validation

The server supports two token validation strategies depending on configuration:

**JWT (recommended)**

When an Auth0 API audience is configured, tokens are signed JWTs. The server validates them locally:

1. Fetches the JSON Web Key Set (JWKS) from Auth0
2. Caches keys for 5 minutes
3. Verifies the JWT signature (RSA)
4. Validates the issuer (`iss`), expiration (`exp`), and audience (`aud`) claims

This is faster because it doesn't require a network call per request.

**Opaque tokens**

When no audience is configured, tokens are opaque. The server validates them by calling Auth0's `/userinfo` endpoint on every request.

This is simpler to set up but adds latency to each request.

***

## Scopes

The server requests the following OAuth scopes during authorization:

| Scope | Purpose |
| - | - |
| `openid` | Required for OIDC — enables ID token issuance |
| `profile` | Access to user's name and nickname |
| `email` | Access to user's email address |
| `offline_access` | Enables refresh tokens for long-lived sessions |

***

## Token flow through the system

Once authenticated, the user's Bearer token flows through the entire system:

```
MCP Client
  │ Bearer token
  ▼
Vero MCP Server ──validates──▶ Auth0 (JWKS or /userinfo)
  │ Same Bearer token
  ▼
Vero API (plaid-wrapper) ──validates──▶ Auth0
  │
  ▼
Plaid / Gmail / OCR services
```

The MCP server does not mint its own tokens. It validates the Auth0 token and passes it through to the Vero API, which performs its own independent validation.

***

## PKCE support

The authorization server metadata advertises support for `S256` code challenge method (PKCE). MCP clients that implement PKCE will use it automatically for added security during the authorization code exchange.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.