Live Football API now ships a fully-built, embeddable widget — drop one script tag into your site and get a live match list, a single match scoreboard, league standings, a team page, or a player profile, all rendered and kept up to date automatically. No frontend code, no polling logic. This guide covers embedding it correctly and securely.
How This Differs from the CSB Widget
If you've used the csb_url iframe from /live_match_details before, this is a different, more general system. CSB is a single match visualization; the new widget is a full mini-app that can render five different views (match list, single match, league, team, player) and is configured entirely from your dashboard.
Step 1: Create a Widget in the Dashboard
Go to Dashboard → Widgets and create a widget, choosing which features are enabled (events, lineups, h2h, standings, etc.) and which domain(s) are allowed to load it. This gives you a permanent widget token — but note this token alone cannot fetch data.
Step 2: Understanding the Two-Token System
This is the part worth reading carefully, because it's the whole point of the design:
- Widget token (permanent, shown in your dashboard) — identifies which widget configuration to use, but cannot pull data on its own
- Session token (1-hour expiry, obtained via
/widget/session) — the actual credential the embedded script uses to fetch data, generated server-side by exchanging your widget token + real API key
Your real api_key is never sent to the browser. Only the short-lived session token ends up in your page source — and because it expires in an hour, a copied token becomes useless on its own without your action.
Step 3: Exchanging Your Widget Token for a Session Token
This call must happen server-side, since it requires your real API key:
import requests
response = requests.get(
'https://live-football-api.com/widget/session.php',
params={'api_key': 'YOUR_REAL_KEY', 'token': 'YOUR_WIDGET_TOKEN'}
).json()
session_token = response['data']['session_token']
print(session_token, response['data']['expires_in']) # 3600 seconds
Step 4: Embedding the Widget
Pass the session token into the script tag on your page — this is what's safe to render server-side into your HTML:
<script src="https://live-football-api.com/widget/widget.js"
data-token="SESSION_TOKEN_FROM_STEP_3" async></script>
With no extra attributes, this renders the default view: today's match list with a live/upcoming/finished filter and a date picker.
Step 5: Choosing a Different View
Add data-type and data-id to render a specific match, league, team, or player instead:
<!-- Single match scoreboard with tabs for events, lineups, h2h -->
<script src="https://live-football-api.com/widget/widget.js"
data-token="SESSION_TOKEN"
data-type="match"
data-id="lfa4phmwb3bhclg7aqht1ajcwk" async></script>
<!-- League standings and fixtures -->
<script src="https://live-football-api.com/widget/widget.js"
data-token="SESSION_TOKEN"
data-type="league"
data-id="lfa-premier-league" async></script>
<!-- Team squad, match history, standings -->
<script src="https://live-football-api.com/widget/widget.js"
data-token="SESSION_TOKEN"
data-type="team"
data-id="lfa-man-city" async></script>
<!-- Player profile -->
<script src="https://live-football-api.com/widget/widget.js"
data-token="SESSION_TOKEN"
data-type="player"
data-id="lfa-haaland" async></script>
Step 6: Controlling Size and Language
Three optional attributes control sizing and localization without any custom CSS:
<script src="https://live-football-api.com/widget/widget.js"
data-token="SESSION_TOKEN"
data-lang="tr"
data-max-width="100%"
data-height="90vh" async></script>
data-lang forces a specific language regardless of the visitor's browser; data-max-width and data-height stretch the widget to fill a container — the default is a fixed 480px card.
Step 7: Keeping the Session Token Fresh
Since the session token expires after an hour, a static page needs a way to refresh it periodically. A cron job that regenerates the token and rewrites the page is the standard approach:
#!/bin/bash
# Runs every 30 minutes — comfortably inside the 1-hour expiry
SESSION=$(curl -s "https://live-football-api.com/widget/session.php?api_key=YOUR_KEY&token=YOUR_WIDGET_TOKEN" | jq -r '.data.session_token')
sed -i "s/data-token=\"[^\"]*\"/data-token=\"$SESSION\"/" /var/www/yoursite/page-with-widget.html
If your page is server-rendered on every request instead (Node, PHP, Django, etc.), it's simpler — just fetch a fresh session token as part of rendering the page, no cron needed:
// Node/Express example, rendered per-request
app.get('/live-scores', async (req, res) => {
const session = await fetch(
`https://live-football-api.com/widget/session.php?api_key=${process.env.LFA_KEY}&token=${process.env.LFA_WIDGET_TOKEN}`
).then(r => r.json());
res.render('live-scores', { sessionToken: session.data.session_token });
});
Why the Token Is Allowed to Be Visible in Page Source
The session token will always be visible in your page's HTML or network tab — that's unavoidable for any client-side credential. The security model here relies on the 1-hour expiry rather than secrecy: if someone copies the token from your page source, it stops working within the hour on its own, with no action needed from you.
Frequently Asked Challenges
- Don't put your real api_key in client-side code, ever — only the
/widget/sessionexchange call should use it, and that call must run on your server - Don't hardcode a session token and forget about it — it will silently stop working after an hour; build the refresh step in from the start
- Restrict allowed domains in the dashboard — this stops someone else from copying your widget token (though not a valid session token, which is separate) and using your configuration elsewhere
Frequently Asked Questions
Does loading the widget cost credits per pageview?
The widget draws from the same credit-metered endpoints under the hood via your API key — check your dashboard for how widget usage is counted, since a high-traffic embedded widget can consume credits at the rate of your visitor traffic, not just your own testing.
Can I style the widget to match my site's theme?
Sizing is controlled via data-max-width and data-height; for deeper visual customization beyond size, check your dashboard's widget configuration options, since the widget itself doesn't accept arbitrary custom CSS.
What happens if my session token expires while a visitor is viewing the page?
Since the widget script loads once per page view, an expired token would affect a page loaded after expiry rather than a session already in progress — refreshing the token well within the hour window (e.g. every 30 minutes) avoids visitors ever hitting an expired token.
Is there a way to embed the widget without any server-side code at all?
Since the /widget/session exchange requires your real API key and must not run in the browser, some server-side piece — even a simple scheduled script rewriting a static file — is required. A fully static, code-free embed isn't possible with this security model.
