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

# Configuring Connections

> Step-by-step guide to setting up BYOK + OAuth connections.

## Overview

This guide walks through configuring connections so you can proxy API requests through agntdata using your own vendor credentials.

## Prerequisites

* An agntdata account with an active workspace.
* An account with the external service.
* For BYOK vendors — an API key with the right scopes.
* For OAuth vendors — login access to the vendor's account.

## OAuth flow

OAuth is the recommended path for any vendor that supports it (Google Docs, Google Sheets, Slack, Stripe, Linear, Cal.com, Supabase, Dub).

<Steps>
  <Step title="Open Connections">
    From the dashboard sidebar, click **Connections**, then **Add connection**, and pick the vendor.
  </Step>

  <Step title="Start the OAuth flow">
    Click **Connect**. agntdata redirects you to the vendor's consent screen.
  </Step>

  <Step title="Approve scopes">
    Review the requested scopes (every vendor lists what we ask for) and approve.
  </Step>

  <Step title="Land back in agntdata">
    The vendor redirects to `/webhooks/inbound/oauth/<vendor>/callback`. agntdata exchanges the code for tokens, stores them encrypted, and routes you back to the connection page with a green check.
  </Step>
</Steps>

If you started the OAuth flow from the **Build with AI** chat (the Builder surfaces a `request_connection` card when it needs a vendor), the callback brings you back into the same chat so you can resume the conversation without context loss.

OAuth tokens are refreshed automatically. If a refresh fails (e.g. the vendor revoked the token), the connection is marked `needs_reauth` and the dashboard shows a re-connect button.

## BYOK (paste an API key)

For vendors without an OAuth flow — Exa, Instantly, HeyReach, AgentMail, Attio, PostHog, SocialScraper, the X official API, memelord — you paste a key.

<Steps>
  <Step title="Open Connections">
    From the dashboard sidebar, click **Connections**, then **Add connection**, and pick the vendor.
  </Step>

  <Step title="Generate the vendor API key">
    Follow the vendor's docs to create a key with the minimum scopes you need.
  </Step>

  <Step title="Paste and save">
    Paste the key into agntdata's form, give the connection a name (helps when you've connected multiple accounts of the same vendor), and save.
  </Step>
</Steps>

Keys are encrypted at rest. Your client apps never see them — they only ever see your agntdata API key.

## When both OAuth and BYOK are available

For vendors that support both, agntdata prefers OAuth. If you've completed an OAuth install and *also* pasted a key, requests use the OAuth credential and the pasted key is ignored. The dashboard surfaces a warning when both exist.

For OAuth-capable vendors, the paste-key path is hidden in the dashboard by default — connect through OAuth.

## Making requests

Once the connection is configured, hit the proxy with your agntdata API key:

```bash theme={null}
curl -X GET "https://api.agntdata.dev/v1/connections/:vendor/endpoint" \
  -H "Authorization: Bearer YOUR_AGNTDATA_API_KEY"
```

agntdata forwards the request — including path and query params — to the vendor, attaching your stored credential.

## Managing connections

### Viewing

The Connections page lists every configured connection with its auth type (OAuth vs. BYOK), connected status, and last successful call.

### Updating credentials

* **BYOK** — click the connection, paste a new key, save.
* **OAuth** — click **Reconnect** to step through the consent flow again. The old install is replaced atomically.

### Disabling

Toggle **Active** to off. Proxied requests will return a `CONNECTION_DISABLED` error until you flip it back on.

### Deleting

<Warning>
  Deleting a connection removes the stored credentials permanently and revokes the corresponding MCP tools from any agent using them.
</Warning>

1. Click the connection.
2. Click **Delete** and confirm.

Any deployed agent that referenced this connection will see the `connection_<vendor>_*` tools disappear from its tool list on the next `tools/list` call.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 / 403 from the vendor">
    * For BYOK: verify the key is correct and has the required scopes. Vendor portals usually let you regenerate.
    * For OAuth: the token may have been revoked. Click **Reconnect** to refresh.
  </Accordion>

  <Accordion title="Rate-limit errors">
    External services enforce their own rate limits separately from agntdata's. Check the vendor's docs and back off as the vendor specifies.
  </Accordion>

  <Accordion title="Connection timeout">
    The external service may be experiencing issues. Check our [health status page](https://status.agntdata.dev) for upstream dependencies, then retry.
  </Accordion>

  <Accordion title="OAuth callback failed">
    Most callback failures are scope mismatches (the consent screen returned without granting a required scope) or expired install state. Restart the OAuth flow from **Connections**.
  </Accordion>
</AccordionGroup>

## Best practices

<AccordionGroup>
  <Accordion title="Use descriptive names">
    When you have multiple connections to the same vendor (e.g. two Stripe accounts), name them so it's obvious which is which.
  </Accordion>

  <Accordion title="Least privilege">
    BYOK keys should grant only the scopes the agent actually needs. OAuth scopes are determined by agntdata's app — we publish the minimal set on each vendor page.
  </Accordion>

  <Accordion title="Rotate periodically">
    Vendor security policies usually recommend rotating long-lived API keys every 90 days or so. The dashboard's connection page tracks creation date.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Connections overview" icon="plug" href="/connections/overview">
    The full list of supported vendors.
  </Card>

  <Card title="Tools" icon="screwdriver-wrench" href="/agents/tools">
    How connections show up as MCP tools.
  </Card>
</CardGroup>