Registration¶

Follow these five steps to start using the API:

1. Register - Create an API consumer, your application's registered access to the API
2. Get approval - Firstbeat activates your API consumer
3. Grant access - Your Coach authorizes data access
4. Authenticate - Implement secure API authentication (api key, JWT)
5. Test the connection - Verify everything works

Create API Consumer¶

First step is to create an API consumer. Think of it as your application's identity card for accessing the API. It identifies who you are and controls which team data you can access.

Pick a name that unambiguously identifies the organization, department or individual who will control the API registration. At best, this is a clear, human-readable name like "Firstbeat Technologies". Make a POST request to the registration endpoint:

import requests

response = requests.post(
    "https://api.firstbeat.com/v1/account/register",
    json={"consumerName": "Fitview Analytics Ltd"}
)

credentials = response.json()
print(f"Consumer ID: {credentials['id']}")
print(f"Shared Secret: {credentials['sharedSecret']}")

curl 'https://api.firstbeat.com/v1/account/register' \
--data '{"consumerName": "Fitview Analytics Ltd"}'

curl -d "{"consumerName": "Fitview Analytics Ltd"}" \
https://api.firstbeat.com/v1/account/register

You'll receive credentials for your API consumer:

{
  "id": "87a05c83-d5b7-46ba-aa4a-32f56cd284d5",
  "consumerName": "Fitview Analytics Ltd",
  "sharedSecret": "8d5b6d12-61c5-4303-9ae3-c1837a15034b"
}

Save these credentials securely. You'll need:

• id - identifies your API consumer to Firstbeat
• sharedSecret - needed to generate authentication tokens (keep this private)

Ask Firstbeat to Approve your API Consumer¶

Send your consumer details to Firstbeat support for activation. Email sports-cloud-api@firstbeat.com with:

1. Your consumerName and id
2. Customer account names to link (e.g., "Jyväskylä Bears", "Acme Ice Hockey Club")
3. Contact people for API notifications (name + email)

Email template:

Subject: New API consumer approval

Hi,

I have created a new Sports Cloud API consumer:

* consumerName: Fitview Analytics Ltd
* id: 87a05c83-d5b7-46ba-aa4a-32f56cd284d5

Please connect this consumer to customer accounts:
- Jyväskylä Bears
- Acme Ice Hockey Club

Contact info for API updates:
- John Doe, john.doe@acme.com (developer)
- Joe Doe, joe.doe@acme.com (team manager)

Best regards,
John Doe

Grant Access To Data¶

Once Firstbeat has approved your consumer, a Coach on your team must authorize it to access account data in Sports Cloud.

Steps in Sports Cloud:

1. Go to sports.firstbeat.com
2. Click the settings menu (top left corner)
3. Navigate to Cloud API section
4. Accept the license agreement (if not already accepted)
5. Select your API consumer from the list
6. Check the account checkbox to grant access
7. Save settings

Implement JWT Creation¶

Implement JWT (JSON Web Token) generation in your application using your consumer id and sharedSecret. JWTs are used along with API keys to authenticate API requests.

import jwt
import time

def create_jwt_token(consumer_id: str, shared_secret: str) -> str:
    """Generate a JWT token valid for 5 minutes."""
    now = int(time.time())
    payload = {
        "iss": consumer_id,
        "iat": now,
        "exp": now + 300  # 5 minutes
    }
    return jwt.encode(payload, shared_secret, algorithm="HS256")

# Usage
token = create_jwt_token(
    consumer_id="87a05c83-d5b7-46ba-aa4a-32f56cd284d5",
    shared_secret="8d5b6d12-61c5-4303-9ae3-c1837a15034b"
)
print(f"Bearer {token}")

const jwt = require('jsonwebtoken');

function createJwtToken(consumerId, sharedSecret) {
    const now = Math.floor(Date.now() / 1000);
    const payload = {
        iss: consumerId,
        iat: now,
        exp: now + 300  // 5 minutes
    };
    return jwt.sign(payload, sharedSecret, { algorithm: 'HS256' });
}

// Usage
const token = createJwtToken(
    '87a05c83-d5b7-46ba-aa4a-32f56cd284d5',
    '8d5b6d12-61c5-4303-9ae3-c1837a15034b'
);
console.log(`Bearer ${token}`);

Token format in API requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjMzhlMjU2ZC0xMWVlLTRmNWQtYWI0NS1iNjJkMDU3NGE3ZmQiLCJpYXQiOjE1ODg2NzQxNzYsImV4cCI6MTU4ODY3NDQ3Nn0.BQpPdmyM4KikNFIRisKdOkFRCADCA1bQpKUzBUWy3QA

For more complete code examples including full authentication workflows, see the Sample Code page.

Retrieve your API Key¶

Retrieve your API key by calling the account/api-key endpoint with a valid JWT:

import requests

# Generate JWT first (using function from previous step)
token = create_jwt_token(consumer_id, shared_secret)

response = requests.get(
    "https://api.firstbeat.com/v1/account/api-key",
    headers={"Authorization": f"Bearer {token}"}
)

api_key = response.json()["apikey"]
print(f"API Key: {api_key}")

curl 'https://api.firstbeat.com/v1/account/api-key' \
    --request GET \
    --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...'

Response:

{"apikey": "cXvpCBUzG64orvHXA5taA2Et2hWGr6Gh1LqL90hx"}

API key format in requests:

x-api-key: cXvpCBUzG64orvHXA5taA2Et2hWGr6Gh1LqL90hx

Test Access¶

Verify your setup by listing the accounts your consumer can access:

import requests

# Use both JWT and API key
token = create_jwt_token(consumer_id, shared_secret)

response = requests.get(
    "https://api.firstbeat.com/v1/sports/accounts",
    headers={
        "Authorization": f"Bearer {token}",
        "x-api-key": api_key
    }
)

accounts = response.json()
print(f"Connected accounts: {len(accounts['accounts'])}")
for account in accounts['accounts']:
    print(f"  - {account['name']} (ID: {account['accountId']})")

curl 'https://api.firstbeat.com/v1/sports/accounts' \
    --request GET \
    --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...' \
    --header 'x-api-key: cXvpCBUzG64orvHXA5taA2Et2hWGr6Gh1LqL90hx'

Success response:

{
  "accounts": [
    {
      "accountId": "3-12345",
      "name": "Jyväskylä Bears",
      "authorizedBy": {
        "coachId": 67890
      }
    },
    {
      "accountId": "3-67891",
      "name": "Acme Ice Hockey Club",
      "authorizedBy": {
        "coachId": 45678
      }
    }
  ]
}