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

# Authentication errors

> Troubleshoot 401, 403, and missing credential errors.

Authentication errors usually happen when your upstream API doesn't receive the credentials it expects, or when the provided credentials don't have permission to access the requested operation.

## Common error types

### 401 Unauthorized

A `401` response usually means:

* A credential is missing
* The token or API key is invalid
* The token has expired
* The required authentication header wasn't sent correctly

### 403 Forbidden

A `403` response usually means:

* The credential is valid
* It doesn't have permission to access the requested API operation

This often happens when the token lacks the required scopes, roles, or access policies.

<Info>
  A `401` usually points to credential identity or formatting. A `403` usually points to permission.
</Info>

## Quick checks

### Verify the client configuration

Open the [**Setup** page](/guides/setup) and confirm that:

* All required headers are configured
* Environment variables are correctly named
* Credentials are being passed to the client

### Check Bearer token formatting

If your API uses Bearer authentication, make sure the value includes the required prefix:

```http theme={null}
Authorization: Bearer YOUR_TOKEN
```

### Verify API key header names

Header names must match exactly, including capitalization, spelling, and dashes.

Example:

```http theme={null}
X-API-Key: YOUR_API_KEY
```

### Replace expired credentials

Ensure the token or API key:

* Has not expired
* Has not been revoked
* Is still active in your upstream system

### Confirm permissions

Verify that the credential is allowed to access the selected API operation.

A valid token can still return `403 Forbidden` if it lacks the required permissions.

### Reconnect the client

After updating environment variables or credentials:

* Restart the MCP client
* Or reconnect the server

Some clients cache configuration until restarted.

### Query API keys

If your API expects authentication as a query parameter:

* Use the gateway header provided by 0mcp
* Do not place secrets directly in the MCP endpoint URL

0mcp automatically converts the secure header into the required query parameter before forwarding the request upstream.

<Warning>
  Never add an API key directly to the MCP endpoint URL or commit it to a shared client configuration.
</Warning>

Read the [authentication model](/concepts/authentication-model) for details about pass-through credentials and supported methods.

## Still not working?

To continue debugging:

1. Review the failed request in [**Logs**](/guides/logs).
2. Compare the timestamp with your upstream API logs.
3. Confirm your [OpenAPI security scheme](/api-sources/openapi) matches your actual API authentication requirements.

Your upstream API logs are the best source for diagnosing detailed authentication failures.