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

# Dub

> Proxy Dub.co API requests through agntdata — connect via OAuth or paste a Dub API key.

## Overview

[Dub](https://dub.co) is a link-attribution platform — branded short links, conversion tracking, and affiliate programs. The Dub connection on agntdata supports two auth methods:

* **OAuth 2.0** (recommended) — click **Connect with Dub** and approve access. agntdata stores the access + refresh tokens encrypted and refreshes them automatically.
* **API key** (BYOK) — paste a Dub API key generated at [dub.co/settings/tokens](https://dub.co/settings/tokens).

Either way, your agents just call `/v1/connections/dub/*` with an agntdata API key — agntdata picks the right upstream credential for your workspace.

* **Base URL**: `https://api.agntdata.dev/v1/connections/dub/*`
* **Dub auth**: agntdata injects `Authorization: Bearer <access_token_or_api_key>`

## Setup

### Connect with Dub (recommended)

<Steps>
  <Step title="Click Connect with Dub">
    In the agntdata dashboard open **Integrations**, pick **Dub**, and click **Connect with Dub**. You'll be redirected to Dub's consent screen.
  </Step>

  <Step title="Approve scopes">
    Approve the requested scopes (links / tags / domains / folders / analytics / workspaces read+write). You'll be redirected back with a confirmation banner.
  </Step>

  <Step title="Call Dub">
    Make requests to `https://api.agntdata.dev/v1/connections/dub/*` with your agntdata API key. Dub access tokens expire after \~2 hours; agntdata refreshes them transparently using the stored refresh token.
  </Step>
</Steps>

Behind the scenes agntdata runs a standard OAuth 2.0 authorization-code flow with PKCE against `https://app.dub.co/oauth/authorize` and stores the access + refresh tokens in `oauth_installs`, encrypted at rest.

### Paste an API key (fallback)

If OAuth isn't available for your deployment — or you'd rather hand agntdata a scoped key — click **Use API key instead** in the connection dialog and paste a Dub API key. Generate one in Dub at **Settings → Tokens** ([dub.co/settings/tokens](https://dub.co/settings/tokens)).

## Examples

### List links

```bash theme={null}
curl -X GET "https://api.agntdata.dev/v1/connections/dub/links" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"
```

### Create a short link

```bash theme={null}
curl -X POST "https://api.agntdata.dev/v1/connections/dub/links" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://agntdata.dev","key":"welcome"}'
```

### Pull analytics

```bash theme={null}
curl -X GET "https://api.agntdata.dev/v1/connections/dub/analytics?event=clicks&interval=7d" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"
```

## Endpoints supported

The Dub connection exposes the full Dub REST API surface, including:

* **Links** — create, update, upsert, list, delete short links
* **Analytics** — clicks, leads, sales, revenue by dimension
* **Events** — paginate raw click, lead, and sale events
* **Conversion tracking** — `POST /track/lead`, `POST /track/sale`
* **Tags & folders** — organize links with role-based access control
* **Customers** — read and update customers tied to conversion events
* **Custom domains** — manage branded short-link domains
* **Partners, bounties, commissions, payouts** — on Advanced or higher

## OAuth scopes

When using OAuth, agntdata requests: `workspaces.read`, `links.read`, `links.write`, `tags.read`, `tags.write`, `domains.read`, `domains.write`, `folders.read`, `folders.write`, `analytics.read`, `user.read`. API-key access is scoped by whatever permissions you attach to the key in Dub's dashboard.

## Rate limits

Dub applies per-workspace rate limits. agntdata surfaces upstream 429 responses as-is.

## FAQ

**Which auth method should I use?** Prefer OAuth when the dashboard offers it — no long-lived credentials to rotate, and revoking access in Dub also kills agntdata's access. Use the API-key path when OAuth isn't available for your deployment or when you specifically want a scoped, single-purpose token.

**What happens if I have both a pasted key and an OAuth install?** The OAuth install wins — agntdata uses it on every proxied call. Remove the install from the dashboard if you want to force the BYOK path.

**Do I pay agntdata credits for Dub calls?** No. Dub bills your Dub workspace directly — agntdata only proxies the request and doesn't charge credits for `/v1/connections/*`.

**Which Dub plan do I need?** Link management works on any plan; conversion tracking (`/track/lead`, `/track/sale`) requires a Dub Business plan or higher.

**Where does agntdata store my Dub credentials?** OAuth tokens live encrypted in `oauth_installs`; pasted API keys live encrypted in `workspace_integrations`. Both are decrypted only in-memory when proxying a request.

**What happens when an OAuth token expires?** Dub access tokens expire after \~2 hours. agntdata refreshes them transparently using the stored refresh token; you never need to reconnect unless you revoke the install in Dub or the dashboard.