OAuth2 Provider and API Tokens | blade47/dub Wiki | doc0

Public

OAuth2 Provider and API Tokens | blade47/dub Wiki | doc0

Configuration Property	Value / Length	Prefix	Purpose
`CLIENT_ID`	24 chars	`dub_app_`	Unique public identifier for the OAuth app
`CLIENT_SECRET`	30 chars	`dub_app_secret_`	Confidential credential for confidential clients
`ACCESS_TOKEN`	40 chars	`dub_access_token_`	Bearer token for API authentication
`REFRESH_TOKEN`	40 chars	None (hashed)	Long-lived token for rotating access tokens
`CODE`	40 chars	None	Short-lived authorization code

Scope	Description
`links.read`	Read access to links
`links.write`	Read and Write access to links
`tags.read`	Read access to tags
`tags.write`	Read and Write access to tags
`analytics.read`	Read access to analytics and events
`domains.read`	Read access to domains
`domains.write`	Read and Write access to domains
`user.read`	Read your name, email and profile image
`webhooks.read`	Read access to webhooks
`webhooks.write`	Read and Write access to webhooks
`folders.read`	Read access to folders
`folders.write`	Read and Write access to folders

Model	Primary Key	Unique Constraints	Cascade Relations
`OAuthApp`	`id`	`integrationId`, `clientId`	`oAuthCodes`, `integration`
`OAuthCode`	`id` (cuid)	`code`	`oAuthApp`, `user`, `project`
`OAuthRefreshToken`	`id` (cuid)	`hashedRefreshToken`	`accessToken`, `installedIntegration`

Design Choice	Benefit	Cost
Hashed token storage (`hashedKey`, `hashedRefreshToken`)	Prevents plain-text token exposure if the database is compromised	Requires hashing overhead on every token exchange and verification lookup
Single token per client per user per workspace (`deleteMany` in `waitUntil`)	Prevents accumulation of orphaned active tokens per installation	Automatically revokes concurrent active sessions for the same integration
Deferred cleanup via Vercel `waitUntil`	Speeds up the token response by non-blocking code deletion	Relies on serverless runtime background execution support

HTTP Method	Path	Required Permission	Description
`GET`	`/api/tokens`	`tokens.read`	Lists all non-installation workspace tokens, ordered by last used and creation date.
`POST`	`/api/tokens`	`tokens.write`	Generates a new API token, enforcing workspace limits and scope validations.
`GET`	`/api/tokens/:id`	`tokens.read`	Retrieves details for a specific token ID within the workspace.
`PATCH`	`/api/tokens/:id`	`tokens.write`	Updates a token's name or scopes, refreshing the token cache.
`DELETE`	`/api/tokens/:id`	`tokens.write`	Deletes a token, purging associated machine users and cache entries.

Method	Parameters	Redis Operation	Description
`set`	`{ hashedKey, token }`	`redis.set` with `ex: 86400`	Serializes and caches token metadata for 24 hours.
`get`	`{ hashedKey }`	`redis.get`	Retrieves cached `TokenCacheItem` using the prefixed key.
`delete`	`{ hashedKey }`	`redis.del`	Removes a token cache entry upon revocation or deletion.
`expireMany`	`{ hashedKeys }`	`redis.pipeline()` / `expire(..., 1)`	Instantly expires multiple cache keys using a Redis pipeline.

Configuration Property	Type	Description
`name`	`string`	Human-readable name of the OAuth provider.
`clientId`	`string`	Client identifier assigned by the provider.
`clientSecret`	`string`	Client secret used for token exchanges.
`authUrl`	`string`	Provider authorization endpoint URL.
`tokenUrl`	`string`	Provider token exchange endpoint URL.
`redirectUri`	`string`	Callback URI where the provider redirects after authorization.
`scopes`	`string` (optional)	Space-separated list of requested OAuth scopes.
`redisStatePrefix`	`string`	Prefix key for storing transient state tokens in Upstash Redis.
`tokenSchema`	`z.ZodSchema`	Zod schema for validating token responses.
`bodyFormat`	`"form" \| "json"`	Request body serialization format for token requests.
`responseFormat`	`"json" \| "text"` (optional)	Expected response body format from the token endpoint.
`authorizationMethod`	`"header" \| "body"`	Method for passing client credentials during token exchange.

export async function getValidToken({ stripe }: { stripe: Stripe }) {
  const token = await getSecret<Token>({
    stripe,
    name: "dub_token",
  });
 
  if (!token) {
    throw new Error("Access token not found for the account.");
  }
 
  try {
    await getUserInfo({ token });
  } catch (e) {
    const refreshedToken = await refreshToken({ token });
 
    if (!refreshedToken) {
      console.error("Failed to refresh access token.");
      return null;
    }
 
    await setSecret({
      stripe,
      name: "dub_token",
      payload: JSON.stringify(refreshedToken),
    });
 
    return refreshedToken;
  }
 
  return token;
}