Authentication

All Rhumby API requests require authentication using an API key passed as a Bearer token in the Authorization header.

API Keys

API keys are created and managed in your dashboard. Each key:

• Starts with rhb_ (secret key) or rhumby_pk_ (publishable key)
• Has specific scopes that control what it can access
• Can be revoked at any time
• Should be stored securely and never committed to version control

Using Your API Key

Include your API key in every request:

curl https://rhumby.com/api/v1/events \
  -H "Authorization: Bearer rhb_YOUR_KEY_HERE"

In JavaScript:

const response = await fetch('https://rhumby.com/api/v1/events', {
  headers: {
    'Authorization': 'Bearer rhb_YOUR_KEY_HERE'
  }
});

Scopes

API keys are granted specific scopes that determine what they can access:

When creating an API key, select only the scopes you need. This follows the principle of least privilege and limits the damage if a key is compromised.

Embed Tokens

For client-side widgets, use embed tokens instead of API keys. Embed tokens:

• Start with emb_
• Are safe to expose publicly
• Only work on allowed domains
• Can be restricted to specific events and views
• Don't require an Authorization header

<script src="https://rhumby.com/embed.js"
  data-token="emb_abc123"
  data-event="friday-night-spring-2026"
  data-view="standings">
</script>

Learn more in the Embed SDK documentation.

Rate Limits

Free API access includes:

• 1,000 requests per hour per API key
• 10,000 requests per day per organization

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1614556800

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait until the reset time before making additional requests.

Best Practices

Keep Keys Secret

• Store API keys in environment variables, not in code
• Use .env files locally and never commit them
• Rotate keys periodically
• Revoke keys immediately if compromised

Use Appropriate Scopes

• Grant only the scopes needed for each integration
• Use different keys for different purposes
• Never use admin scope unless absolutely necessary

Handle Errors Gracefully

• Check for 401 Unauthorized (invalid or missing key)
• Check for 403 Forbidden (insufficient scope)
• Retry on 429 Too Many Requests after the reset time
• Log errors but never log the full API key

Troubleshooting

401 Unauthorized

Your API key is missing, invalid, or revoked. Check:

• Key is included in the Authorization header
• Key is formatted correctly: Bearer rhb_...
• Key hasn't been revoked in the dashboard

403 Forbidden

Your API key doesn't have the required scope. Check:

• The endpoint you're calling and its required scope
• Your key's scopes in the dashboard
• Consider creating a new key with appropriate scopes

429 Too Many Requests

You've exceeded the rate limit. Wait until the reset time (in the X-RateLimit-Reset header) before retrying.