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

# Authentication

Pomerado MCP uses OAuth bearer tokens scoped to the exact MCP resource URL. Complete your client's OAuth consent flow once for the connection. Pomerado checks account access and permissions automatically on subsequent requests.

## Account access

* Sign in with the Pomerado identity that has access to the requested account and integration.
* Authorize the permissions your client needs in the OAuth flow.
* Reconnect through your client if authorization expires or is revoked.
* Keep website passwords and durable tokens out of MCP messages.

OAuth consent does not bypass account restrictions. Pomerado verifies the current authorization, account status, account permissions and integration access before allowing an action.

The account MCP endpoint remains bounded by your permissions. An individual integration endpoint also restricts discovery and execution to that integration. A public integration still requires MCP authentication.

## Resource scope

Use the endpoint URL exactly as supplied. Tokens for one resource do not authorize another resource, even when both endpoints belong to Pomerado.

* Connect each integration using its own URL and OAuth resource.
* Preserve the URL path without adding query parameters or a trailing slash.
* Authenticate through the MCP client's OAuth flow even if you already signed in to the Dashboard.

The MCP endpoint requires an OAuth token. A Dashboard session cookie or browser session token does not replace it. The account MCP endpoint's token also works on the REST API under `/v1`, and programs without an OAuth flow can use an API key there instead; see [REST API access](rest-api.md).

## OAuth discovery for client developers

An unauthenticated MCP request returns HTTP `401` with a `WWW-Authenticate` header containing `resource_metadata`. Fetch that URL to discover the resource and its authorization server.

| Metadata field | Meaning |
| - | - |
| `resource` | Exact MCP endpoint URL used as the OAuth token audience |
| `authorization_servers` | Authorization server to use for this resource |
| `bearer_methods_supported` | Contains `header` |
| `scopes_supported` | Advertised OAuth scopes when supplied by the server |

For `/mcp/integrations/{integration_id}`, metadata is available through `GET /.well-known/oauth-protected-resource/mcp/integrations/{integration_id}` on the same host. Metadata discovery does not require authentication.

* Discover the authorization server from metadata instead of hard-coding it.
* Request authorization for the exact `resource` value.
* Send the resulting token in the `Authorization` header using the `Bearer` scheme.
* Use the advertised scopes and any required scope in a `WWW-Authenticate` challenge.
* Send MCP messages using `POST` to the resource URL.

A normal browser visit uses `GET` and does not test an MCP connection. The MCP resource accepts `POST` requests. Browser-origin requests must also come from an allowed origin.

## Website sign-in

Pomerado authentication authorizes your client to use Pomerado. A website login authorizes an operation to access that website.

* Use a saved login reference when the operation requires an account on the website.
* Open the protected input page of a job that asks for a login.
* Sign in to Pomerado in the browser to complete the protected form.
* Keep the original MCP connection authorized while the job continues.

Completing a protected form does not give the MCP client broader access. Pomerado checks the original job authority as well as your browser identity. See [saved logins](connections.md).

## Troubleshoot a connection

| Response | Next step |
| - | - |
| `401 unauthorized` | Reconnect through the client's OAuth flow. Confirm the client uses the exact endpoint URL and a token for that resource. |
| `403 forbidden` | Check account access, integration access and the requested permissions. Follow any scope challenge through the client. For browser-based clients, check whether the client origin is supported. |
| `404 not_found` | Copy the endpoint URL again and check that the integration endpoint is ready and enabled. |
| `405 Method Not Allowed` | Use a remote MCP client that sends `POST` requests. Opening the URL in a browser is insufficient. |
| `503 account_unavailable` | Retry later. Pomerado could not verify account access. |

If a connection keeps failing, share the endpoint path and HTTP status with support. Do not share access tokens, session cookies or website credentials. See [limits and errors](limits-and-errors.md) for execution failures.


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