JSON Web Token (JWT)

Some widget use cases require validated data integrity from your backend to prevent misuse by end-users or malicious actors. In such cases, you need to create and sign a JSON Web Token (JWT) using a public/private key pair, and pass that token to widgets as properties.

#Prerequisites

Before starting this tutorial, ensure you have:

• OpenSSL toolkit installed for generating RSA keys
• Backend development environment (Node.js, Python, Java, or similar) capable of signing JWT tokens
• JWT library for your backend language (e.g., jsonwebtoken for Node.js)
• Access to your Sportradar account representative to submit your public key
• Product-specific credentials if implementing Virtual Stadium or Bet Concierge:
  • Virtual Stadium API key (provided during onboarding)
  • Bet Concierge brand ID (provided during onboarding)

#Implementation Steps

The following diagram illustrates the JWT authentication flow:

#Step 1: Generate RSA Key Pair

Generate a pair of RSA keys using the OpenSSL toolkit:

# Generate private key (2048-bit RSA)
openssl genrsa -out rsa-private.pem 2048

# Extract public key from private key
openssl rsa -in rsa-private.pem -pubout -outform PEM -out rsa-public.pem

This creates two files:

• rsa-private.pem - Keep this secure on your backend server
• rsa-public.pem - Send this to Sportradar

Next action: Send the rsa-public.pem file to your Sportradar sales or client setup representative. They will configure the system to validate tokens signed with your private key.

#Step 2: Create JWT Tokens for Users

Every logged-in user requires their own unique JWT. You have two implementation options:

1. Generate on-demand: Create a new token for each page request
2. Cache with TTL: Generate once and cache on your backend until near expiration

#Required Base Claims

All JWT tokens must include these standard claims:

{
    sub: '<id>',
    scope: 'av' | 'vs' | 'sb' | 'av vs sb',
    iat: 1681718850
}

Claim Descriptions:

#Additional Claims for Virtual Stadium

If implementing Virtual Stadium (scope vs), include these additional claims:

{
    // Base claims (sub, scope, iat)
    apiKey: '<key>',
    userId: '<id>',
    displayName: '<userName>',
    userType: 'Normal' | 'VIP'
}

#Additional Claims for Bet Concierge

If implementing Bet Concierge (scope sb), include these additional claims:

{
    // Base claims (sub, scope, iat)
    // ... plus:
    sbBrandId: '<id>',
    sbUserType: '<type>'
}

#Step 3: Sign the Token

Sign the JWT using your private key from Step 1. The signing algorithm must be RS256 (RSA Signature with SHA-256).

#Node.js Example

import jwt from "jsonwebtoken";

// Create token with base claims
const token = jwt.sign(
  {
    sub: "user_12345",
    scope: "av vs", // Audio/video + Virtual Stadium
    // iat is added automatically
  },
  process.env.PRIVATE_SIGNING_KEY,
  { algorithm: "RS256" },
);

#Example With Virtual Stadium Claims

const vsToken = jwt.sign(
  {
    sub: "user_12345",
    scope: "vs",
    apiKey: process.env.VS_API_KEY,
    userId: "user_12345",
    displayName: "John Doe",
    userType: "Normal",
  },
  process.env.PRIVATE_SIGNING_KEY,
  { algorithm: "RS256" },
);

#Step 4: Pass JWT to Widgets

Deliver the signed JWT from your backend to your frontend application, then pass it to the widget during initialization.

#Widget Integration

Pass the JWT as a property when adding the widget using SIR:

SIR("addWidget", "#my-widget", "widget_name_here", {
  jwt: generatedJwtToken,
  // ... other widget properties
});

#Complete Frontend Example

<div id="lmt-widget"></div>

<script>
  // Assume 'userJWT' is passed from your backend
  const userJWT = "{{ jwt_from_backend }}";

  // Initialize Live Match Tracker with JWT for audio/video
  SIR("addWidget", "#lmt-widget", "sr-widgets-lmt", {
    matchId: "sr:match:12345",
    jwt: userJWT,
    // ... other configuration
  });
</script>

#Key Rotation

If you need to rotate your private signing key, follow this process to rotate your JWT signing keys without service interruption:

#Rotation Process

1. Generate new key pair: Create a new RSA key pair using the same process as Step 1
2. Submit public key: Send the new public key to your Sportradar representative
3. Wait for confirmation: Sportradar will add the new key to your configuration and notify you
4. Transition period: Both old and new keys will work simultaneously
5. Update backend: Switch your backend to use the new private key for signing
6. Notify completion: Inform Sportradar when migration is complete
7. Old key disabled: Sportradar will remove the old public key from the configuration