Authentication

The API uses API key authentication. This guide explains how to obtain and use your API key.

Obtaining an API Key

1. Log in to your account dashboard
2. Navigate to the Downloads page (sidebar → Resources → Downloads)
3. Your API key is displayed in the API Key card at the top of that page
4. Click the eye icon to reveal your full API key
5. Copy your API key for use in your applications

Warning: API keys are sensitive credentials. Store them securely and never expose them in client-side code or public repositories.

Using Your API Key

Include your API key in the X-API-Key header of every request:

X-API-Key: your-api-key-here

Example Request

curl -X POST https://api.b337.ai/api/session_ids \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json"

Security Best Practices

1. Use environment variables - Never hardcode API keys in your source code
2. Keep keys secure - Store API keys in secure locations and never commit them to version control

Common Authentication Errors

401 Unauthorized

The API key is missing, invalid, or expired.

{
  "detail": "Invalid or missing API key"
}

Solutions:

• Verify the API key is correct
• Check that the X-API-Key header is included
• Ensure you're using the API key from the Downloads page

403 Forbidden

The API key doesn't have permission for the requested operation.

{
  "detail": "API key does not have permission for this operation"
}

Solutions:

• Verify your account has the necessary permissions
• Contact support if you believe you should have access to this operation

Sample Responses Without a Subscription

Every account gets an API key, so you can try the API before you subscribe. Until your account has an active subscription, the API answers 403 No valid subscription. To get a sample response instead, add this header to your request:

curl -X POST https://api.b337.ai/v3/place_bet \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Bet337-Sandbox: 1" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Every endpoint in these docs then returns an example with the same shape and status code as the real one, plus:

{
  "sandbox": true,
  "sandbox_note": "Sample response: this API key has no active subscription. Subscribe to get live data."
}

The response also carries the header X-Bet337-Sandbox: 1. A sample is never real: no bet is placed, no balance is read and no session is started. Once your subscription is active, the header is ignored and you get live data, so you can leave it in your code.

No account yet? Use the demo key

To try any endpoint in these docs before you sign up, send the demo key demo. It always returns the sample response, with no other header needed:

curl https://api.b337.ai/v3/events -H "X-API-Key: demo"

The demo key never reaches a real account. When you're ready for live data, create an account and use your own key.

Testing Authentication

You can test your API key by making a simple request:

curl -X POST https://api.b337.ai/api/session_ids \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

A successful response confirms your authentication is working:

{
  "sessions": [
    {
      "session_id": "uuid-string",
      "bookie": "tab",
      "username": "user@example.com",
      "active": true
    }
  ]
}

Next Steps

• Make Your First Request - Use your API key to make an API call
• Create a Session - Set up an active session for betting