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

# ETL: MCP Authentication

> How the Integrate.io ETL MCP server authenticates clients: OAuth 2.1 browser sign-in versus a Personal Access Token, and how to revoke access.

The MCP server authenticates every request with a bearer token in the `Authorization` header. The token must belong to a user with access to the account named in the endpoint URL; cross-account requests return `403 Forbidden`. You get that token one of two ways: an OAuth 2.1 browser sign-in that the client manages for you, or a Personal Access Token you mint once and paste in. This page is the single home for both.

## Two ways to authenticate

| | OAuth 2.1 (browser sign-in) | Personal Access Token (PAT) |
| - | - | - |
| Best for | Clients that support OAuth | Clients that need a static credential |
| Setup | Client sends you to a consent screen; nothing to copy or paste | Mint once in the dashboard, paste into config |
| Lifetime | Short-lived, refreshed automatically | 10-year default lifetime |
| Examples | Claude.ai, Claude Desktop connector, Claude Code, ChatGPT, Perplexity | Claude Desktop extension or manual config, Cursor, OpenAI Codex, MCP Inspector, curl |

Which clients are OAuth-first: Claude.ai web, the Claude Desktop custom connector, ChatGPT, and Perplexity authenticate with OAuth. Claude Code supports both. The Claude Desktop extension, clients that speak MCP over stdio (Claude Desktop's manual config, Cursor's bridge fallback, OpenAI Codex), and tools like the MCP Inspector or curl use a static token.

## OAuth 2.1 (browser sign-in)

The easiest way to connect a client that supports OAuth is to skip the token entirely and authenticate in your browser. The client registers itself, sends you to a consent screen, and stores the resulting credentials for you. There is nothing to copy or paste.

You'll see an **Authorize access** screen naming the client, the account it's connecting to, and the host the browser returns to after you approve:

> **Claude Code** is requesting access to your Integrate.io account **your-account** via the MCP server. This will let it read and manage your pipelines, connections, and jobs in this account.
>
> After you approve, you'll be returned to: **localhost**

Check the host before you continue. Integrate.io sends the authorization code to this host. For a client running on your machine, such as Claude Code, the host is `localhost` or `127.0.0.1`. If you don't recognize the host, click **Cancel**.

Click **Authorize**. The browser hands the client back its credentials and you can close the tab. The consent screen is locked to the account subdomain the client connected to, so a client can only ever be granted access to that one account.

### What OAuth grants

* Access is **account-wide** with the same permissions as the signed-in user, identical in scope to a Personal Access Token. Whether write tools are available depends on the account's read or write access level, not on the grant.
* Tokens are short-lived and refreshed automatically by the client, so you won't be prompted again every couple of hours during normal use.
* The connection appears in **Settings → Developer Settings → Connected Applications** under the client's name (e.g. "Claude Code"), alongside any Personal Access Tokens, so you can audit and revoke it in one place.

> [!NOTE]
>
> Integrate.io uses the OAuth 2.1 Authorization Code flow with PKCE (S256), the same standard used by major SaaS MCP connectors. After you click **Authorize**, your browser returns to the client's local callback (e.g. `http://localhost:…/callback`) and shows a brief "Authentication Successful" page rendered by the client; that page comes from the MCP client, not from Integrate.io.

## Personal Access Token (PAT)

For clients that need a static bearer credential, mint a Personal Access Token from the **Connected Applications** page in your dashboard. No curl, no password grant, no token expiry to manage.

1. Sign in to your dashboard and navigate to **Settings → Developer Settings → Connected Applications**. *(Direct URL: `https://dashboard.xplenty.com/<your-account>/settings/developer/connected_applications`)* If you don't see the **Connected Applications** link in the sidebar, contact Integrate.io support to request access.
2. Click **+ Create new connection**.
3. Give it a recognizable name (e.g. "Claude Desktop on Macbook") and click **Create token**.
4. The token is displayed **once** in a reveal modal. Click **Copy** before closing the modal. Integrate.io does not store the plaintext token and cannot show it again. If you lose it, revoke the connection and create a new one.

The reveal modal also includes ready-to-paste configuration snippets for Claude Desktop, Claude Code, the MCP Inspector, and curl.

> [!TIP]
>
> The **Connected Applications** page also has a **Quick install for Claude Desktop** card with a one-click `.mcpb` extension download. If Claude Desktop is your client, see [Claude Desktop (one-click extension)](https://www.integrate.io/docs/etl/mcp-connect-claude.md#claude-desktop-one-click-extension).

**PAT scope and security notes:**

* PATs are **account-wide** and carry the same permissions as the user who created them.
* The read-only versus read + write split is applied at the **account level**, not the token level. Every token issued for the same account sees the same tool set. See [Safety, audit, and read-only mode](https://www.integrate.io/docs/etl/integrateio-mcp-server.md#safety-audit-and-read-only-mode) for how the split works. Contact Integrate.io support if you need finer-grained scoping.
* PATs have a **10-year lifetime** by default. Treat them like passwords: store in a secrets manager, not in plain text.
* Token rotation: revoke the existing connection in **Connected Applications** and create a new one. Update your MCP client config with the new token.

### Alternative: OAuth password grant (legacy)

If you can't use Connected Applications (e.g., automation that must mint tokens programmatically without a logged-in user), you can still use the OAuth Resource Owner Password Credentials grant. **These tokens expire after two hours**, so you'll need to refresh them regularly.

```bash theme={null}
curl -X POST 'https://api.xplenty.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "password",
    "email": "you@your-org.com",
    "password": "your-password"
  }'
```

The response includes the `access_token`:

```json theme={null}
{
  "access_token": "ABC123...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "created_at": 1234567890
}
```

For interactive use, prefer Connected Applications. The 10-year PAT lifetime means you set it up once and forget it.

## Revoking and re-authenticating

* **Revoke:** open **Settings → Developer Settings → Connected Applications**, find the client or token, and click **Revoke**. Access stops immediately and the client must authorize again to reconnect. A revoked bearer token stops working everywhere it's pasted.
* **Re-authenticate (OAuth):** if you authorize the same client again, the new session **replaces** the previous one for that client name, so you won't accumulate duplicate entries in Connected Applications. The consent screen still appears each time; that approval is the security checkpoint and is expected on every authorization.

## Reachability for cloud connectors

Some clients, such as Claude.ai web and ChatGPT, connect from the vendor's cloud rather than from your device. For those connectors the endpoint must be reachable from the public internet (the production URL is). If your account sits behind a firewall or IP allowlist, make sure the vendor's egress can reach `api.xplenty.com` before setting up a cloud connector.

## Known gotcha: static token vs OAuth fallback

If you configure a client with a static token that is rejected (revoked, mistyped, or for the wrong account), some clients report a failed connection instead of falling back to OAuth browser sign-in. If a token-based connection fails, verify the token in **Connected Applications** first. To switch a client to OAuth, remove the static credential from its config so the client runs browser sign-in instead. See [Troubleshooting](https://www.integrate.io/docs/etl/mcp-troubleshooting.md) for specific error symptoms.


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