Authentication

Learn how to authenticate your API requests using API keys.

API Key Authentication

The SnipLink API uses API keys for authentication. Include your API key in theX-API-Key header of every request:

X-API-Key: snip_your_api_key_here

API Key Format

All API keys follow a consistent format for easy identification:

Authentication Methods

The API supports two authentication methods:

API Key Scopes

API keys can be created with specific scopes to limit their permissions. Following the principle of least privilege, you should only grant the scopes your application actually needs.

Scope Reference

Scope Hierarchy

Scopes follow a hierarchy where higher privilege scopes automatically include lower ones:

• :delete scopes include :write and :read
• :write scopes include :read
• workspace:admin includes workspace:read and all api-keys:* scopes
• * (full access) includes all scopes

Common Scope Patterns

Here are recommended scope combinations for common use cases:

Scope Errors

When an API key attempts to access a resource without the required scope, you'll receive a 403 Forbidden response:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "API key lacks required scope: links:write",
    "details": {
      "requiredScope": "links:write",
      "grantedScopes": ["links:read", "analytics:read"]
    }
  }
}

Security Best Practices

1. Never expose API keys in client-side code - API keys should only be used in server-side code.
2. Use environment variables - Store API keys in environment variables, not in your codebase.
3. Use minimal scopes - Only request the scopes your application needs.
4. Rotate keys regularly - Generate new API keys periodically and revoke old ones. The API supports a grace period during rotation.
5. Set expiration dates - Create API keys with expiration dates for temporary integrations.

API Key Rotation

The SnipLink API supports secure key rotation with a configurable grace period, allowing you to rotate keys without downtime.

How Key Rotation Works

1. Generate new key - Call the rotate endpoint to generate a new API key.
2. Grace period - Both old and new keys work during the grace period (default: 24 hours, max: 7 days).
3. Update your systems - Deploy the new key to your applications.
4. Old key expires - After the grace period, only the new key works.

Rotation Example

// Request
POST /v1/workspaces/{workspaceId}/api-keys/{apiKeyId}/rotate
{
  "gracePeriodMs": 86400000  // 24 hours (optional)
}

// Response
{
  "apiKey": {
    "id": "key_abc123",
    "name": "Production API Key",
    "keyPrefix": "snip_xyz",
    "version": 2
  },
  "newPlaintextKey": "snip_newkey123...",  // Only returned once!
  "previousKeyExpiresAt": "2025-01-16T12:00:00.000Z"
}

Zero-Downtime Rotation Process

// 1. Rotate the key (both keys now work)
const response = await fetch(
  `https://api.sniplink.co/v1/workspaces/${workspaceId}/api-keys/${keyId}/rotate`,
  {
    method: 'POST',
    headers: { 'X-API-Key': currentApiKey },
    body: JSON.stringify({ gracePeriodMs: 3600000 }) // 1 hour
  }
);
const { newPlaintextKey, previousKeyExpiresAt } = await response.json();

// 2. Store the new key in your secrets manager
await secretsManager.update('SNIPLINK_API_KEY', newPlaintextKey);

// 3. Deploy new key to all instances
// Both keys work until previousKeyExpiresAt

// 4. After grace period, old key stops working automatically

Example: Environment Variables

# .env (do not commit this file!)
SNIPLINK_API_KEY=snip_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
SNIPLINK_WORKSPACE_ID=ws_xxxxxxxxxxxxx

// Usage in Node.js
const apiKey = process.env.SNIPLINK_API_KEY;
const workspaceId = process.env.SNIPLINK_WORKSPACE_ID;

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

Troubleshooting

401 Unauthorized

If you receive a 401 error, check the following:

• Verify your API key is correct and starts with snip_
• Ensure the X-API-Key header is set correctly
• Check that your API key has the required scopes for the endpoint
• Confirm the API key hasn't been revoked or expired

403 Forbidden

A 403 error typically means your API key doesn't have the required scope for the operation. Check the endpoint documentation to see which scopes are required.