JWT Authentication

Virtual Stadium uses JWT tokens to authenticate users and control access to features. JWT tokens are created using the RS256 algorithm (RSA signature with SHA-256).

#Overview

To authenticate users with Virtual Stadium:

1. Generate an RSA key pair (2048-bit recommended)
2. Share your public key with Sportradar
3. Sign JWT tokens server-side using your private key
4. Include required claims in your token payload
5. Pass the token when initializing Virtual Stadium

If you haven't set up JWT authentication with Sportradar yet, start by generating your RSA keys.

#RSA Key Generation

Generate an RSA key pair using the OpenSSL toolkit. The following commands create a 2048-bit RSA key pair.

After generating your keys:

• Public key (rsa-public.pem): Share with Sportradar via your communication channel
• Private key (rsa-private.pem): Store securely on your servers and use to sign tokens

Generate RSA Key Pair:

# Generate private key (2048-bit)
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

Verify Keys:

# View private key
openssl rsa -in rsa-private.pem -text -noout

# View public key
openssl rsa -in rsa-public.pem -pubin -text -noout

rsa-public.pem (Share with Sportradar):

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
...
-----END PUBLIC KEY-----

#The Token Object

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

Learn more about JWT structure.

JWT Structure:

{
  "header": {
    "alg": "RS256",
    "typ": "JWT"
  },
  "payload": {
    "iss": "your-organization",
    "sub": "user123",
    "scope": "vs",
    "iat": 1681718850,
    "apiKey": "your-api-key",
    "userId": "user123",
    "displayName": "John Doe",
    "userType": "Normal"
  },
  "signature": "..."
}

#Token Payload Attributes

#Standard JWT Claims

iss string required

Issuer identifier - identifies the principal that issued the JWT. Typically your organization or application identifier.

sub string required

Subject identifier - a unique identifier for the end user. Can be a user ID or salted hash if you prefer not to expose real user IDs.

scope string required

Space-separated list of permissions. Use vs for Virtual Stadium access. For multiple Sportradar products, combine scopes (e.g., av vs).

iat integer required

Issued At timestamp - Unix timestamp (seconds) when the token was issued. Most JWT libraries add this automatically. Used to calculate token expiration (default: 16 hours from iat).

exp integer optional

Expiration timestamp - Unix timestamp (seconds) when the token expires. If omitted, defaults to 16 hours after iat.

Standard JWT Claims Example:

{
  "iss": "your-organization",
  "sub": "user123",
  "scope": "vs",
  "iat": 1681718850,
  "exp": 1681776450
}

Multiple Products Scope:

{
  "scope": "av vs"
}

Calculate Expiration:

// 16 hours from now
const iat = Math.floor(Date.now() / 1000);
const exp = iat + (16 * 60 * 60);

// Token payload
{
  "iat": iat,
  "exp": exp
}

#Virtual Stadium Specific Claims

apiKey string required

Your Virtual Stadium API key provided by Sportradar during onboarding.

userId string required

Unique identifier for the user. Should match the sub claim value.

displayName string required

User's display name shown in the Virtual Stadium interface (visible to other users).

userType enum required

User access level. VIP users have highlighted chat messages and special privileges.

Possible enum values:

• Normal - Standard user access
• VIP - Enhanced user with highlighted messages

Virtual Stadium Claims Example:

{
  "apiKey": "vs_live_abc123xyz789",
  "userId": "user123",
  "displayName": "John Doe",
  "userType": "Normal"
}

VIP User Example:

{
  "apiKey": "vs_live_abc123xyz789",
  "userId": "premium_user_456",
  "displayName": "Jane Smith",
  "userType": "VIP"
}

#Complete Token Payload Example

All required claims combined in a single payload object.

Complete JWT Payload:

{
  "iss": "your-organization",
  "sub": "user123",
  "scope": "vs",
  "iat": 1681718850,
  "exp": 1681776450,
  "apiKey": "vs_live_abc123xyz789",
  "userId": "user123",
  "displayName": "John Doe",
  "userType": "Normal"
}

#Create a Token

Sign your JWT using the RS256 algorithm with your private key. Most JWT libraries support RS256 signing.

#Parameters

payload object required

Token payload containing all required claims (see Token Payload Attributes above).

privateKey string required

Your RSA private key in PEM format.

algorithm string required

Must be RS256 (RSA signature with SHA-256).

#Returns

Returns a signed JWT token string that can be used to authenticate with Virtual Stadium.

import jwt from 'jsonwebtoken';
import fs from 'fs';

// Load private key
const privateKey = fs.readFileSync(
  'rsa-private.pem',
  'utf8'
);

// Create token
const token = jwt.sign(
  {
    iss: 'your-organization',
    sub: 'user123',
    scope: 'vs',
    apiKey: 'vs_live_abc123xyz789',
    userId: 'user123',
    displayName: 'John Doe',
    userType: 'Normal'
  },
  privateKey,
  { algorithm: 'RS256' }
);

console.log(token);

Example Token Output:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIiwic2NvcGUiOiJ2cyIsImlhdCI6MTY4MTcxODg1MCwiYXBpS2V5Ijoidi3NfbGl2ZV9hYmMxMjN4eXo3ODkiLCJ1c2VySWQiOiJ1c2VyMTIzIiwiZGlzcGxheU5hbWUiOiJKb2huIERvZSIsInVzZXJUeXBlIjoiTm9ybWFsIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...