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).

1. Open Connections

   From the dashboard sidebar, click Connections, then Add connection, and pick the vendor.

2. Start the OAuth flow

   Click Connect. agntdata redirects you to the vendor’s consent screen.

3. Approve scopes

   Review the requested scopes (every vendor lists what we ask for) and approve.

4. 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.

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.

1. Open Connections

   From the dashboard sidebar, click Connections, then Add connection, and pick the vendor.

2. Generate the vendor API key

   Follow the vendor’s docs to create a key with the minimum scopes you need.

3. 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.

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:

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

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

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

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.

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.

Connection timeout

The external service may be experiencing issues. Check our health status page for upstream dependencies, then retry.

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.

Best practices

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.

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.

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.

Next steps

Connections overview

The full list of supported vendors.

Tools

How connections show up as MCP tools.