Generating API keys

This guide covers creating, using, and managing API keys for server-to-server integrations.

What are API keys?

API keys allow your systems to authenticate with the Scalar API. With an API key, you can programmatically:

• Retrieve and create ideas
• Access survey responses
• Manage customers
• And more

Generating your first API key

1. Go to Settings > API (in the API & Integrations section)
2. Click Generate key
3. Copy the key immediately and store it securely

Important: The full API key is only shown once. If you lose it, you'll need to generate a new one.

API key format

Keys have a prefix indicating the environment:

Example: scalar_live_abc123def456...

Storing keys securely

Your API key grants access to your company's data. Store it safely:

Do:

• Store in environment variables
• Use a secret manager (AWS Secrets Manager, HashiCorp Vault, etc.)
• Restrict access to production secrets

Don't:

• Commit keys to version control (Git, SVN)
• Include in client-side code (JavaScript bundles, mobile apps)
• Share keys in chat, email, or documentation
• Log keys in application logs

Using keys in API requests

Header authentication (recommended)

Use the Authorization header with the Api-Key scheme:

curl -H 'Authorization: Api-Key YOUR_API_KEY' \
  'https://your-workspace.scalar.co.za/api/v1/ideas/'

Or use the X-API-Key header:

curl -H 'X-API-Key: YOUR_API_KEY' \
  'https://your-workspace.scalar.co.za/api/v1/ideas/'

HTTP Basic authentication

For tools that only support Basic Auth, use your API key as the username with a blank password:

curl -u 'YOUR_API_KEY:' \
  'https://your-workspace.scalar.co.za/api/v1/ideas/'

Monitoring usage

Track your API usage:

1. Go to Settings > API
2. View:
   • Rate limit: Requests per hour allowed
   • Requests today: Requests made today
   • Last used: When the key was last used

Rate limits

API requests are rate-limited per hour. If you exceed the limit:

• Requests return HTTP 429 (Too Many Requests)
• Wait until the rate limit window resets
• Consider optimising your integration to make fewer requests

Rotating keys

If you suspect your key has been compromised, rotate it immediately:

1. Go to Settings > API
2. Click Regenerate key
3. Copy the new key
4. Update all your integrations with the new key

The old key is revoked immediately. Requests using the old key will fail.

Revoking keys

To fully disable API access:

1. Go to Settings > API
2. Click Revoke key
3. Confirm the revocation

All API requests using this key will fail immediately.

Error handling

Who can manage API keys?

Only Admins can:

• Generate API keys
• View API key status
• Regenerate keys
• Revoke keys

Next steps

• Setting up webhooks - Receive real-time event notifications
• Scalar API documentation - Full API reference