Single Sign-On (Partner Integration)

Sign your students into ByteXL directly from your own student management system. Once a student is logged in to your application, a "Go to ByteXL" button takes them straight to their ByteXL dashboard — with no second login and no separate ByteXL password to manage.

This guide is written for the engineering team integrating on the partner side.

Method: Signed-token redirect
Token: JWT, signed with HS256
Effort: One backend endpoint on your side

How It Works

When a student clicks "Go to ByteXL" inside your application, your server creates a short-lived, cryptographically signed token that names the student, and redirects the browser to ByteXL with that token. ByteXL verifies the signature, finds the matching student, starts their ByteXL session, and lands them on the dashboard.

The token is signed with a secret that only your server and ByteXL know, so it never travels through the browser as anything other than a one-time, expiring value.

Step	Where	What happens
1	Student, in your app	Already logged in, clicks "Go to ByteXL".
2	Your server	Mints a signed JWT with the student's email and a 60-second expiry.
3	ByteXL	Verifies the token, matches the student, starts their session.
4	Student, in ByteXL	Lands on the dashboard, fully logged in.

What ByteXL Gives You

Ahead of integration, the ByteXL team will send you the following over a secure channel. Treat all three as server-side configuration — never hard-code the secret into a repository or ship it to the browser.

Item	Example	What it is
`partnerId`	`acme-college`	A stable identifier for your institution. You include it in every token.
Signing secret	a long random string	The shared secret used to sign (you) and verify (ByteXL) tokens. Store it server-side only.
SSO endpoint	`…/api/_callback/sso/partner`	The ByteXL URL you redirect students to.

Keep the secret safe

The signing secret is what authorises a login. Store it in your server-side secrets manager, and never commit it to source control or expose it to the browser.

Add the "Go to ByteXL" Flow

Store the credentials. Put the partnerId, signing secret, and endpoint URL into your server-side configuration (environment variables or a secrets manager).
Add a button that hits your backend. The "Go to ByteXL" button should call a route on your own server — not link directly to ByteXL. Only your server can hold the secret and mint the token.
Mint a signed token for the logged-in student. In that route, read the currently authenticated student's email from your session, then generate a JWT signed with your secret.
Redirect the browser to ByteXL. Append the token as a token query parameter on the SSO endpoint and issue an HTTP redirect:
```
GET https://app.bytexl.ai/api/_callback/sso/partner?token=YOUR_SIGNED_JWT
```
Confirm the landing. On success, the student's browser ends up on the ByteXL dashboard with an active session. On failure, ByteXL redirects to a login page with an error reason (see Error Reference).

The SSO Token

Sign a JSON Web Token using algorithm HS256 and the shared secret. Include these claims:

Claim	Required	Description
`sub`	Required	The student's email address. Must match the email ByteXL holds for that student.
`partnerId`	Required	The identifier ByteXL issued to you, e.g. `acme-college`.
`iat`	Required	Issued-at time (Unix seconds). Most JWT libraries set this for you.
`exp`	Required	Expiry time. Keep it short — 60 seconds or less from `iat`.
`jti`	Required	A unique, random token ID (e.g. a UUID). Used to reject replayed tokens.
`name`	Optional	The student's full name, used only when a new account is provisioned.

The email is the identity

ByteXL matches students by the sub email. Make sure the email in your system is the same one the student is enrolled under in ByteXL, otherwise the login will be rejected.

Code Samples

The server-side route mints the token and redirects. Adapt it to your framework — the shape is the same in every language.

Node.js

// Express route behind your own login
const jwt = require("jsonwebtoken");
const { randomUUID } = require("crypto");

app.get("/go-to-bytexl", requireLogin, (req, res) => {
  const token = jwt.sign(
    {
      sub: req.user.email,        // enrolled ByteXL email
      name: req.user.fullName,
      partnerId: "acme-college",
    },
    process.env.BYTEXL_SSO_SECRET, // server-side secret
    { algorithm: "HS256", expiresIn: "60s", jwtid: randomUUID() }
  );

  res.redirect(
    `https://app.bytexl.ai/api/_callback/sso/partner?token=${token}`
  );
});

Python (Flask)

# Flask route behind your own login
import jwt, uuid, time, os
from flask import redirect

@app.route("/go-to-bytexl")
def go_to_bytexl():
    now = int(time.time())
    token = jwt.encode(
        {
            "sub": current_user.email,      # enrolled ByteXL email
            "name": current_user.full_name,
            "partnerId": "acme-college",
            "iat": now,
            "exp": now + 60,
            "jti": str(uuid.uuid4()),
        },
        os.environ["BYTEXL_SSO_SECRET"],    # server-side secret
        algorithm="HS256",
    )
    return redirect(
        f"https://app.bytexl.ai/api/_callback/sso/partner?token={token}"
    )

PHP

// Using firebase/php-jwt, behind your own login
use Firebase\JWT\JWT;

function goToByteXL($student) {
    $now = time();
    $token = JWT::encode([
        "sub"       => $student->email,     // enrolled ByteXL email
        "name"      => $student->fullName,
        "partnerId" => "acme-college",
        "iat"       => $now,
        "exp"       => $now + 60,
        "jti"       => bin2hex(random_bytes(16)),
    ], getenv("BYTEXL_SSO_SECRET"), "HS256"); // server-side secret

    header("Location: https://app.bytexl.ai/api/_callback/sso/partner?token=" . $token);
    exit;
}

Security Checklist

Confirm each of these before going live:

Keep the secret server-side. Never expose it in browser code, mobile apps, URLs, or logs. Anyone with the secret can impersonate any of your students.
Sign every token, always with HS256. Do not accept an algorithm from the token itself, and never send an unsigned (alg: none) token.
Keep tokens short-lived. A 60-second (or shorter) exp limits the window for any leaked link.
Use a unique jti per token. ByteXL rejects any token ID it has already seen, so a captured link cannot be replayed.
Always use HTTPS. Mint tokens only for students authenticated in your own system at that moment.
Plan for rotation. If a secret is ever exposed, contact ByteXL to rotate it. Build the secret as swappable config, not a constant.

Matching & Provisioning Students

ByteXL locates the student by the sub email within your institution. There are two policies for a student who signs in via SSO but doesn't yet have a ByteXL account — decide with your ByteXL account manager which one applies to you:

Policy	Behaviour on first SSO login
Pre-onboarded only (default)	Only students already created in ByteXL can sign in. Unknown emails are rejected. You manage the roster through your normal ByteXL onboarding.
Just-in-time provisioning	A student with no ByteXL account yet is created automatically on first sign-in, using the `name` from the token and mapped into your institution.

Error Reference

If a token can't be accepted, ByteXL redirects to a login page with a reason. Use these to debug during integration:

Reason	Cause	Fix
`invalid_signature`	Token wasn't signed with the matching secret.	Confirm you're using the exact secret ByteXL issued you.
`token_expired`	More than 60s passed, or server clocks are out of sync.	Mint the token at click time; sync your server clock (NTP).
`replay_detected`	This `jti` was already used.	Generate a fresh unique `jti` for every request.
`unknown_partner`	`partnerId` is missing or not recognised.	Use the exact `partnerId` ByteXL issued you.
`user_not_found`	No ByteXL student matches the email.	Onboard the student, or enable just-in-time provisioning.

Testing & Go-Live

Confirm the endpoint URL, your partnerId, and the provisioning policy with your ByteXL account manager.
Verify a known student lands on the dashboard, and that an unknown or expired token is rejected cleanly.
Share your button placement and the source IP range of your servers with ByteXL if an allowlist is required.
Roll out to your students once one real student has been confirmed end to end.

For credentials, secret rotation, environment URLs, or help during integration, contact your ByteXL account manager or the ByteXL integrations team.

How It Works​

What ByteXL Gives You​

Add the "Go to ByteXL" Flow​

The SSO Token​

Code Samples​

Node.js​

Python (Flask)​

PHP​

Security Checklist​

Matching & Provisioning Students​

Error Reference​

Testing & Go-Live​