Skip to main content
The Dub API uses API tokens to authenticate requests. You can create and manage your API tokens from your workspace settings.

​
API Token Types

Dub supports two types of API tokens: Workspace API tokens are scoped to a specific workspace and provide granular access control through scopes.
  • Start with the prefix dub_
  • Scoped to a single workspace
  • Support fine-grained permissions via scopes
  • Can be set to expire automatically
  • Rate limits based on your workspace plan

​
2. Legacy Personal API Keys

Personal API keys are older tokens that are being phased out.
Personal API keys are deprecated. We recommend migrating to workspace API tokens for better security and access control.

​
Creating an API Token

  1. Navigate to your workspace settings
  2. Go to the API section
  3. Click “Create Token”
  4. Select the appropriate scopes for your use case
  5. (Optional) Set an expiration date
  6. Copy and securely store your token
API tokens are only shown once during creation. Store them securely - you won’t be able to see them again.

​
Using Your API Token

Include your API token in the Authorization header using the Bearer authentication scheme: 
curl https://api.dub.co/links?workspaceId=ws_abc123 \\
  -H "Authorization: Bearer dub_xxxxxxxxxxxxx"

​
Authorization Header Format

The Authorization header must follow this exact format: 
Authorization: Bearer YOUR_API_TOKEN
Make sure to include the Bearer prefix. Requests without this prefix will return a 400 Bad Request error with the message: “Misconfigured authorization header. Did you forget to add ‘Bearer’?”

​
Token Scopes

Workspace API tokens support granular permission scopes to limit what actions a token can perform. Common scopes include:
  • links.read - Read link data
  • links.write - Create and update links
  • analytics.read - Access analytics data
  • domains.read - Read domain information
  • domains.write - Manage domains
When creating a token, select only the scopes needed for your integration to follow the principle of least privilege.

​
Token Security Best Practices

Never expose your API tokens in client-side code, public repositories, or version control systems.
  1. Store securely: Use environment variables or secure secret management systems
  2. Rotate regularly: Periodically rotate your tokens, especially if they may have been exposed
  3. Use expiration: Set expiration dates on tokens when possible
  4. Scope appropriately: Only grant the minimum scopes required
  5. Monitor usage: Regularly review token usage in your workspace settings

​
Token Expiration

Tokens can be configured to expire automatically. When a token expires:
  • API requests will return a 401 Unauthorized error
  • The error message will indicate: “Unauthorized: Access token expired.”
  • You’ll need to create a new token to continue making API requests

​
Authentication Errors

​
Missing Authorization Header

Status Code: 401 Unauthorized 
{
  "error": {
    "code": "unauthorized",
    "message": "Missing Authorization header.",
    "doc_url": "https://dub.co/docs/api-reference/errors#unauthorized"
  }
}

​
Invalid API Token

Status Code: 401 Unauthorized 
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://dub.co/docs/api-reference/errors#unauthorized"
  }
}

​
Expired Token

Status Code: 401 Unauthorized 
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Access token expired.",
    "doc_url": "https://dub.co/docs/api-reference/errors#unauthorized"
  }
}

​
Misconfigured Header

Status Code: 400 Bad Request 
{
  "error": {
    "code": "bad_request",
    "message": "Misconfigured authorization header. Did you forget to add 'Bearer '? Learn more: https://d.to/auth",
    "doc_url": "https://dub.co/docs/api-reference/errors#bad-request"
  }
}

​
Workspace Identification

When using workspace API tokens (tokens starting with dub_), you must identify which workspace the request is for: 
# Using query parameter
curl https://api.dub.co/links?workspaceId=ws_abc123 \\
  -H "Authorization: Bearer dub_xxxxxxxxxxxxx"

# Using workspace slug
curl https://api.dub.co/links?workspaceId=my-workspace \\
  -H "Authorization: Bearer dub_xxxxxxxxxxxxx"
The workspace ID associated with a token is verified during authentication. Tokens can only access resources within their associated workspace.

​
Rate Limiting & Authentication

Rate limits are applied per API token and vary based on your workspace plan. See the Rate Limits page for more information.

Build docs developers (and LLMs) love

Get started for freeTalk to us