Workspaces

Workspaces help you organize links, manage team access, and separate environments for different projects or clients.

What is a Workspace?

A workspace is an isolated container for your links, domains, and team members. Each workspace has its own:

• Links - Short links created within the workspace
• Custom Domains - Branded domains for your short links
• Team Members - Users with access to manage the workspace
• API Keys - Scoped access credentials for the workspace
• Analytics - Click tracking and statistics

Workspace Architecture

All API requests are scoped to a workspace using the workspaceId parameter in the URL path:

https://api.sniplink.co/v1/workspaces/{workspaceId}/links
https://api.sniplink.co/v1/workspaces/{workspaceId}/domains
https://api.sniplink.co/v1/workspaces/{workspaceId}/analytics

This design provides:

• Isolation - Links in one workspace don't affect another
• Billing separation - Each workspace can have its own plan
• Team flexibility - Different teams can manage different workspaces

Finding Your Workspace ID

You can find your workspace ID in the dashboard URL or via the API. The ID is prefixed with ws_:

https://app.sniplink.co/dashboard/ws_abc123def456/links

Via API

List all workspaces you have access to:

curl https://api.sniplink.co/v1/workspaces \
  -H "X-API-Key: snip_your_api_key_here"

Response:

{
  "success": true,
  "data": [
    {
      "id": "ws_abc123def456",
      "name": "My Company",
      "slug": "my-company",
      "role": "owner",
      "plan": "pro",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "ws_xyz789ghi012",
      "name": "Client Project",
      "slug": "client-project",
      "role": "admin",
      "plan": "free",
      "createdAt": "2024-02-20T14:45:00Z"
    }
  ]
}

Creating a Workspace

Create a new workspace via the API. You'll automatically become the owner of the new workspace.

curl -X POST https://api.sniplink.co/v1/workspaces \
  -H "X-API-Key: snip_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Project",
    "slug": "new-project"
  }'

Team Member Roles

Workspaces support role-based access control with four permission levels:

Inviting Team Members

curl -X POST https://api.sniplink.co/v1/workspaces/{workspaceId}/invites \
  -H "X-API-Key: snip_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "teammate@example.com",
    "role": "admin"
  }'

API Keys and Workspaces

API keys are scoped to specific workspaces and permissions. When you create an API key, you specify which workspace it can access:

Best Practices

1. One workspace per project/client - Keep links organized and billing separate.
2. Use descriptive names - Make it easy for team members to identify workspaces.
3. Minimal permissions - Give team members only the access they need.
4. Separate test and production - Create a test workspace for development to avoid affecting production links.
5. Store workspace ID in environment variables - Don't hardcode workspace IDs in your application.

Example: Multi-Workspace Setup

# .env
# Production workspace
SNIPLINK_WORKSPACE_ID=ws_prod123
SNIPLINK_API_KEY=sk_live_xxx

# Test workspace (for development)
SNIPLINK_TEST_WORKSPACE_ID=ws_test456
SNIPLINK_TEST_API_KEY=sk_test_xxx

// Use the appropriate workspace based on environment
const workspaceId = process.env.NODE_ENV === 'production'
  ? process.env.SNIPLINK_WORKSPACE_ID
  : process.env.SNIPLINK_TEST_WORKSPACE_ID;

const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.SNIPLINK_API_KEY
  : process.env.SNIPLINK_TEST_API_KEY;

const response = await fetch(
  `https://api.sniplink.co/v1/workspaces/${workspaceId}/links`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url: 'https://example.com' }),
  }
);