Skip to main content
Workspaces are the foundation of your Dub organization. They allow you to organize links, manage team members, and track analytics across your link attribution campaigns.

​
What is a Workspace?

A workspace in Dub represents your organization or project. Each workspace has:
  • Unique slug: Used for your workspace URL and partner programs
  • Custom domains: Connect your own domains for branded short links
  • Team members: Collaborate with different permission levels
  • Usage limits: Based on your plan (links, clicks, conversions)
  • Analytics: Track performance across all your links
Workspaces are also referred to as “projects” in the Dub codebase and API.

​
Creating a Workspace

1

Navigate to Workspace Creation

From your dashboard, click the workspace selector and choose “Create workspace” or visit the workspaces page.
2

Enter Workspace Details

Fill in the required information:
Name: The display name of your company or product (e.g., “Acme, Inc.”)This is how your workspace will appear throughout the Dub interface.
3

Configure Conversion Tracking (Optional)

Enable automatic conversion tracking for all new links created in this workspace.
You can always enable conversion tracking for individual links later, but enabling it workspace-wide ensures all new links are tracked by default.
4

Create Workspace

Click “Create workspace” to finalize. You’ll be automatically redirected to your new workspace.

​
Workspace Settings

After creating your workspace, you can configure various settings:

​
General Settings

  • Name and Logo: Update your workspace branding
  • Slug: Cannot be changed after creation
  • Billing Cycle: View when your billing cycle starts
  • Plan Tier: See your current plan and limits

​
Usage and Limits

Each workspace has usage limits based on your plan: 
{
  usage: number,              // Total events tracked
  usageLimit: number,         // Max events per billing cycle
  linksUsage: number,         // Current links created
  linksLimit: number,         // Max links allowed
  payoutsUsage: number,       // Partner payouts processed (cents)
  payoutsLimit: number,       // Max payouts per cycle (cents)
  domainsLimit: number,       // Max custom domains
  tagsLimit: number,          // Max tags for organization
  foldersLimit: number,       // Max folders
  usersLimit: number,         // Max team members
  aiUsage: number,            // AI features used
  aiLimit: number,            // AI usage limit
}
When you exceed usage limits, certain features may be restricted. Upgrade your plan to increase limits.

​
Team Management

Invite team members with different permission levels:
  • Owner: Full access to all workspace settings, billing, and resources
  • Member: Can create and manage links, view analytics
  • Viewer: Read-only access to links and analytics
  • Billing: Manage billing and subscription settings only

​
Domain Management

1

Add Custom Domain

Navigate to Settings > Domains and click “Add Domain”
2

Configure DNS

Add the required DNS records to your domain provider:
  • A record pointing to Dub’s servers
  • TXT record for domain verification
3

Verify Domain

Once DNS records propagate, click “Verify” to activate your domain
4

Set as Primary

Mark your domain as primary to use it as the default for new links

​
Conversion Tracking Settings

Enable conversion tracking features for your workspace:
  • Conversion Enabled: Automatically enable tracking for new links
  • Publishable Key: Client-side key for tracking scripts
  • Allowed Hostnames: Whitelist domains for client-side tracking
// Example: Using the publishable key
import { Analytics } from '@dub/analytics/react';

<Analytics 
  publishableKey="pk_live_xxxxx" 
  allowedHostnames={['yourdomain.com']}
/>

​
Workspace API Integration

​
Creating a Workspace via API

const response = await fetch('/api/workspaces', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme, Inc.',
    slug: 'acme',
    logo: 'https://example.com/logo.png', // Optional
    conversionEnabled: true, // Optional
  }),
});

const { id: workspaceId } = await response.json();

​
Workspace Schema

The workspace object returned from the API: 
{
  id: string,                    // Unique workspace ID
  name: string,                  // Workspace name
  slug: string,                  // Unique workspace slug
  logo: string | null,           // Logo URL
  plan: 'free' | 'pro' | 'business' | 'enterprise',
  planTier: number,              // Current plan tier
  totalLinks: number,            // Total links in workspace
  usage: number,                 // Current usage
  conversionEnabled: boolean,    // Auto-enable tracking
  dotLinkClaimed: boolean,       // Free .link domain claimed
  createdAt: Date,               // Creation timestamp
  users: [
    {
      role: 'owner' | 'member' | 'viewer' | 'billing',
      defaultFolderId: string | null,
    }
  ],
  domains: [
    {
      slug: string,              // Domain name
      primary: boolean,          // Is primary domain
      verified: boolean,         // Domain verified
    }
  ],
}

​
Best Practices

Use folders to organize links by campaign or product, and tags to add metadata for filtering and analytics.
Monitor your workspace usage regularly to avoid hitting limits during critical campaigns.
Assign appropriate roles to team members to maintain security and prevent accidental changes.
Turn on workspace-wide conversion tracking to automatically track all links without manual configuration.

​
Switching Between Workspaces

You can be a member of multiple workspaces:
  1. Click the workspace selector in the top navigation
  2. Choose the workspace you want to switch to
  3. All links, analytics, and settings will update to reflect the selected workspace
Each workspace is completely isolated with its own links, domains, and analytics.

​
Deleting a Workspace

Deleting a workspace is permanent and cannot be undone. All links, analytics data, and settings will be permanently deleted.
To delete a workspace:
  1. Navigate to Settings > General
  2. Scroll to the “Danger Zone”
  3. Click “Delete Workspace”
  4. Confirm by typing the workspace slug
  5. All data will be permanently removed

Build docs developers (and LLMs) love

Get started for freeTalk to us