Authentication

API Keys

All API requests require authentication via an API key. You can generate API keys from the Ssemble dashboard — click your profile icon and select API Keys.

API keys are prefixed with sk_ssemble_ and should be kept secret. Do not expose them in client-side code or public repositories.

Generating an API key

1. Sign in to the Ssemble dashboard
2. Click your profile icon in the top-right corner and select API Keys
3. Click Generate New Key
4. Copy the key immediately — it won't be shown again
5. Store the key securely in your environment variables

You can generate multiple API keys for different applications or environments. Each key is tied to your account and shares the same credit balance and rate limits.

Passing the API key

Include your API key in every request header using either format:

X-API-Key header (recommended)

curl -H "X-API-Key: sk_ssemble_your_key_here" \
  https://aiclipping.ssemble.com/api/v1/templates

const response = await fetch('https://aiclipping.ssemble.com/api/v1/templates', {
  headers: {
    'X-API-Key': 'sk_ssemble_your_key_here'
  }
});

Authorization Bearer header

curl -H "Authorization: Bearer sk_ssemble_your_key_here" \
  https://aiclipping.ssemble.com/api/v1/templates

const response = await fetch('https://aiclipping.ssemble.com/api/v1/templates', {
  headers: {
    'Authorization': 'Bearer sk_ssemble_your_key_here'
  }
});

Both formats are fully supported. The X-API-Key header is recommended because it avoids confusion with other Bearer token systems (like OAuth).

Authentication errors

The API returns specific error codes depending on the authentication issue:

Missing API key (401)

No X-API-Key or Authorization header was included in the request.

{
  "error": {
    "code": "missing_api_key",
    "message": "API key is required. Please provide it in X-API-Key header or as Bearer token.",
    "details": null
  }
}

Invalid API key (401)

The key doesn't start with sk_ssemble_, has an incorrect length, doesn't match any active key, or has been revoked.

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key format",
    "details": null
  }
}

Subscription required (403)

The account associated with the API key does not have an active subscription.

{
  "error": {
    "code": "subscription_required",
    "message": "Active subscription required to use API",
    "details": null
  }
}

Insufficient credits (403)

The account has no remaining credits. Each short creation request consumes 1 credit.

{
  "error": {
    "code": "insufficient_credits",
    "message": "No credits available",
    "details": {
      "required": 1,
      "available": 0
    }
  }
}

Error codes summary

Rate limit headers

Every API response includes rate limit information in the headers, regardless of whether the request succeeded or failed:

Reading rate limit headers

const response = await fetch('https://aiclipping.ssemble.com/api/v1/templates', {
  headers: { 'X-API-Key': 'sk_ssemble_your_key' }
});
 
const remaining = response.headers.get('X-RateLimit-Remaining-Hour');
const resetAt = response.headers.get('X-RateLimit-Reset');
 
console.log(`Requests remaining this hour: ${remaining}`);
console.log(`Resets at: ${resetAt}`);

See Rate Limits for details on limits per endpoint.

Security best practices

• Environment variables — Store API keys in environment variables (SSEMBLE_API_KEY), never hardcode them in source code.

  # .env file
  SSEMBLE_API_KEY=sk_ssemble_your_key_here

  const API_KEY = process.env.SSEMBLE_API_KEY;

• Server-side only — Never use API keys in client-side JavaScript (browser code). Make API calls from your backend server.

• Separate keys — Use different API keys for development and production environments. This makes it easy to rotate or revoke keys without affecting all environments.

• Rotate periodically — Generate new keys and revoke old ones periodically from the dashboard.

• Monitor usage — Check your API usage and credit consumption from the Ssemble dashboard to detect unexpected activity.

• Git safety — Add .env files to your .gitignore to prevent accidentally committing API keys to version control.

  # .gitignore
  .env
  .env.local
  .env.production