Balla StatsAll Tutorials

API Keys

Create API keys to integrate external systems, build custom dashboards, or automate workflows with Balla Stats data.

Intermediate
12 minutes

Prerequisites

Before creating API keys, you need:

  • A Balla Stats account
  • PRO plan or higher

Plan limits: FREE = 0 keys, PRO = 3 keys (1,000 req/hr), TEAM = 10 keys (10,000 req/hr), ENTERPRISE = 50 keys (100,000 req/hr).

Programmatic API Access

Create API keys to integrate external systems, build custom dashboards, or automate workflows with Balla Stats data.

Scoped Permissions

Granular access control

Rate Limiting

Per-key request limits

Usage Tracking

Full audit trail

What You'll Learn
  • Navigate to API Keys
  • Create your first key
  • Copy and save securely
  • Use your API key
  • Monitor usage
  • Rotate or revoke keys
1
Navigate to API Keys

In the dashboard sidebar, click API Keys. This page shows all your existing keys and lets you create new ones.

API Keys management page
2
Create Your First Key

Click "Create API Key", enter a descriptive name, and select the scopes your key needs. Available scopes include: read, write, matches, players, teams, seasons, and stats.

Create API Key dialog with scope selection

Start with read-only scope and add write permissions only when needed. This follows the principle of least privilege.

3
Copy and Save Your Key

Your key will be displayed in the format balla_sk_[64 hex characters]. This is the only time you will see the full key. Copy it immediately and store it in a secure location.

API key secret shown once - copy it now

Your API key will only be shown once. Copy it now and store it securely. It cannot be retrieved later. If you lose it, you will need to rotate or create a new key.

4
Use Your API Key

Include your API key in the Authorization header of your HTTP requests:

curl -H "Authorization: Bearer balla_sk_..." \
  https://api.ballastats.com/api/matches

Or in JavaScript:

const response = await fetch(
  'https://api.ballastats.com/api/matches',
  {
    headers: {
      'Authorization': 'Bearer balla_sk_...',
      'Content-Type': 'application/json',
    },
  }
);
const data = await response.json();

All endpoints are documented at /api-docs. See the API Documentation tutorial for details.

5
Monitor Usage

View your key's last used timestamp, total request count, and current rate limit status. Usage statistics help you understand how your integrations are performing and when you might need to upgrade your plan.

API key usage statistics
6
Rotate or Revoke Keys

Rotate a key to create a new one while preserving its name, scopes, and settings. The old key is immediately revoked. Revoke permanently deactivates a key. Revoked keys cannot be reactivated.

Rotating a key invalidates the old key immediately. Update your integrations with the new key before rotating to avoid downtime.

Tips

Use Descriptive Names

Use descriptive names like "Dashboard Bot" or "Stats Exporter" so you can easily identify each key's purpose.

Least Privilege

Follow the principle of least privilege - grant only the scopes your integration actually needs.

Regular Rotation

Rotate keys regularly (every 90 days) for security. Set a reminder to stay on top of key hygiene.

Never Expose Keys

Never commit API keys to source code or share them in plain text. Use environment variables or secret managers.

Common Issues

401 Unauthorized

  • Your key may be inactive, revoked, or expired
  • Check that the key is included in the Authorization header
  • Ensure the header format is Bearer balla_sk_...

403 Forbidden

  • Your key doesn't have the required scope for this endpoint
  • Edit the key to add the necessary scope (e.g., add write for POST requests)
  • Check the API docs for which scopes each endpoint requires

429 Too Many Requests

  • You have exceeded your rate limit for the current hour
  • Wait for the rate limit window to reset, or upgrade your plan for higher limits
  • Check the Retry-After header for when you can retry

Was this article helpful?