Add Agora Live Video to an Existing Website: Tokens, Roles and Reconnects

Many businesses already have a working website or platform and want to add live video: a coaching session, a product launch, a live class or an event broadcast. Rebuilding the whole product is rarely necessary. With the Agora RTC SDK you can add a live streaming module to an existing PHP or Node.js site, as long as you get a few important pieces right. This guide covers the parts that usually decide whether the feature works smoothly in production.

How the pieces fit together

An Agora live stream has three parts. Your server decides who may join which session and issues a short-lived token. The browser or app uses the Agora SDK to join a channel with that token, then publishes or plays audio and video. Agora's network carries the media between hosts and viewers. Your own server never handles the video itself, so you do not need streaming servers or extra bandwidth on your hosting plan.

This split is why live video fits well into an existing platform. Your current login, database and pages stay as they are. You add one endpoint that returns a token, and one page or component that runs the player.

1. Never expose the App Certificate

In the Agora console every project has an App ID and an App Certificate. The App ID is public and goes into your frontend code. The App Certificate is a secret: it is used to sign tokens and must only live on your server, in an environment variable, never in JavaScript or a mobile app build.

Enable the certificate for any project that goes to production. Testing mode without tokens is convenient for a first demo, but it means anyone who finds your App ID can join your channels.

2. Build a small token endpoint

Agora publishes official token builder libraries for several languages. In Node.js the agora-token package provides RtcTokenBuilder; for PHP you can use the token builder classes from Agora's open-source AgoraDynamicKey repository. Each token is built from the App ID, the App Certificate, a channel name, a user ID, a role and an expiry time.

The endpoint should do more than sign a token. Before it returns anything, check that the user is logged in, that the session exists and is currently live or about to start, and that this user is allowed to watch it, for example because they bought the class or belong to the right organisation. Only then return the token. This is where your existing business rules protect the stream.

Use a channel name your server controls, such as the session ID from your database, rather than anything typed by the user. Map your own user IDs to the numeric UID you pass to Agora so you can tell later who joined.

3. Give hosts and viewers different roles

For broadcasts, create the client in live mode. Hosts join with the host role and publish their camera and microphone. Viewers join with the audience role and only subscribe. Issue the publisher role in the token only to users your server has confirmed as hosts; everyone else gets a subscriber token. That way a viewer cannot start publishing just by changing code in the browser.

If you need a viewer to come on stage, for a question or a co-host segment, request a new token with the publisher role from your server and switch the client role. Keep that decision on the server side too.

4. Handle token expiry and reconnects

Tokens expire, and long sessions often run past the first token's lifetime. The Web SDK raises a token-privilege-will-expire event shortly before expiry. Listen for it, fetch a fresh token from your endpoint and call renewToken. If you skip this, users are silently dropped from a session that is still running, which is one of the most common complaints after launch.

Networks also drop, especially on mobile data. Listen to the connection-state-change event and show a clear message such as "Reconnecting…" instead of a frozen video. The SDK retries automatically in many cases, but the viewer needs to know what is happening, and you need a fallback, such as a "Rejoin" button, if the connection does not recover.

5. Design the waiting and empty states

A live page spends a lot of its time not live. Plan what viewers see before the host arrives, when the host's camera is off, when the host leaves, and after the session ends. Subscribe to remote users when they publish, and remove their video tile when they unpublish or leave. These small states make the difference between a feature that feels finished and one that looks broken.

Also handle permissions properly. Browsers ask hosts for camera and microphone access, and the request can be denied or the device can already be in use by another app. Catch those errors and explain the fix in plain language.

6. Check these before launch

Test with real devices on different networks, not just two browser tabs on office Wi-Fi. Confirm the page is served over HTTPS, because browsers block camera access on insecure pages. Test a session longer than your token lifetime. Try joining with an expired or invalid token to make sure it is rejected. Check what happens when the host refreshes the page mid-session. Finally, log join, leave and error events on your server so you can answer support questions with facts.

Mobile apps use the same backend

If you also have a Flutter or React Native app, it can use the same token endpoint and channel names as the website. Agora provides SDKs for both, so web and mobile viewers can join the same live session. Designing the endpoint well once saves you from maintaining two separate permission systems.

Want live video inside your current platform without rebuilding it? I integrate Agora into existing PHP and Node.js products, including the token server, the host and viewer pages, and the mobile app API. Send me a short brief and I will suggest the simplest way to add it.