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.

If you need non-production JWTs—for example development tokens—coordinate with client setup: say which environment the public key you submit is for (prod, nonprod, or dev), and put the same value in the env claim on JWTs you sign with that key (see Claim Descriptions in Step 2). Production-only flows can omit env; it defaults to production behavior.

#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,
  {

#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
  }

#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