API Authentication

Learn about API key types, authentication methods, and security best practices for the cStar API.

Overview

Every API request requires authentication via Bearer token in the Authorization header.

API Key Types

Secret Keys (Server-Side)

sk_live_abc123...   // Production
sk_test_abc123...   // Test mode

• Rate limit: 1,000 requests per hour
• Access: Full CRUD on all resources
• Security: Server-side only — never expose in client code

Publishable Keys (Client-Side)

pk_live_abc123...   // Production
pk_test_abc123...   // Test mode

• Rate limit: 100 requests per hour
• Access: Read-only
• Security: Safe for client-side use (browser, mobile)

Public Library API (No Key Required)

The Library API endpoints are public and require no authentication:

GET /api/library/{team_slug_or_id}/articles
GET /api/library/{team_slug_or_id}/articles/{slug}
GET /api/library/{team_slug_or_id}/categories
GET /api/library/{team_slug_or_id}/search?q={query}

These accept both your team UUID or team slug in the URL path. Rate limited to 200 requests/hour per IP.

Making Requests

curl https://cstar.help/api/v1/teams/{teamId}/tickets \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json"

const response = await fetch('https://cstar.help/api/v1/teams/{teamId}/tickets', {
  headers: {
    'Authorization': 'Bearer sk_your_secret_key',
    'Content-Type': 'application/json'
  }
});

Test Mode

Use test mode keys (sk_test_, pk_test_) to develop without affecting live data. Test and live environments are completely separate.

Error Handling

Authentication errors return 401 Unauthorized:

{
  "success": false,
  "error": "Invalid API key"
}

Rate limit errors return 429 Too Many Requests with a Retry-After header.

Security Best Practices

1. Never expose secret keys in client code — use publishable keys or the public Library API instead
2. Rotate keys periodically — regenerate from Settings → API Keys
3. Use environment variables — don't hardcode keys in source code
4. Use HTTPS only — all API endpoints require HTTPS
5. Monitor usage — check your API key usage in the dashboard

Widget Authentication

The CStarChat widget SDK handles authentication separately using customer accounts:

// Signup a new customer
await CStarChat.signup({
  email: 'customer@example.com',
  name: 'Jane Doe',
  password: 'securepass123'
});

// Login an existing customer
await CStarChat.login({
  email: 'customer@example.com',
  password: 'securepass123'
});

// Sessions persist in localStorage automatically
if (CStarChat.isIdentified()) {
  const customer = CStarChat.getCustomer();
}

For advanced identity verification (Bring Your Own Auth), see the Customer Identity Verification guide.