Let people sign in to your website with their Sensorium Events account. You add a button; they press it, sign in to Sensorium Events in a small window (or create an account there), approve once, and your website receives a signed pass with their basic login details. You check the pass on your server, and they are signed in.
What your website receives
Basic login details, and nothing else. No plan, no contacts, no messages, nothing from their Sensorium Events account beyond this:
| Field | What it is |
|---|---|
id | A permanent ID for this person on your website. It never changes, even if they change their username or email. Each website gets a different ID for the same person, so websites cannot match people up between themselves. Use this to link the person to your own account. |
name | The name they show on Sensorium Events. |
username | Their Sensorium Events username. |
picture | The address of their profile picture, or null. |
email | Their email address. |
email_verified | true when Sensorium Events has confirmed they own that email address. |
The window tells people exactly this before they approve: your website's name, its address, and that it will see their name, username, profile picture and email.
Before you start
- Get your website registered. A Sensorium Events admin adds it in Admin → Settings → Security → Sign in with Sensorium Events, with its name and the addresses it runs on (for example
https://example.comandhttps://www.example.com). If that is not you, ask through Support. - Note your client ID. It looks like
lxs_3f9a…and comes with a ready-made snippet. It is not a secret: it goes in your page. - Use HTTPS. Registered addresses must be https. For trying it on your own computer,
http://localhost(with any port) is allowed.
Add the button
Put this where the button should appear, with your client ID:
<script src="https://sensorium.events/signin.js" data-client="YOUR_CLIENT_ID" data-callback="onSignIn" defer></script>
<div data-linxi-signin></div>
The script draws a button in every element with data-linxi-signin. Its look is self-contained: your styles do not change it, and it does not change yours. You can have several buttons on one page.
Handle the sign-in in the page
When someone signs in, the function named in data-callback is called with one object:
{
token: "eyJhbGciOi…", // the signed pass: send this to your server
user: { // the same details, read from the pass for display
id: "lx_8c1e…", name: "Alex Rivera", username: "alexr",
picture: "https://sensorium.events/api/cloud/file/123", email: "alex@example.com",
email_verified: true
},
nonce: "b41f…" // the one-time value this page put in the pass
}
Send token to your own server and sign the person in there:
<script>
async function onSignIn(result) {
const res = await fetch('/auth/linxi', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token: result.token, nonce: result.nonce })
});
if (res.ok) location.href = '/account';
}
</script>
user on its own. It is read from the pass in the browser, where anyone can change it. It is there so you can say “Hi, Alex” straight away. Only your server's check of token proves who signed in.Prefer events? The same object is sent as a linxi:signin event on document, and a failure as linxi:signin-error:
document.addEventListener('linxi:signin', (e) => console.log(e.detail.user.name));
document.addEventListener('linxi:signin-error', (e) => console.log(e.detail.code, e.detail.message));
Check the pass on your server
Your server sends the pass and your client ID to Sensorium Events, which answers whether it is real, meant for your website, current, and not used before:
POST https://sensorium.events/api/signin/verify
Content-Type: application/json
{ "token": "eyJhbGciOi…", "client_id": "YOUR_CLIENT_ID" }
A good pass answers 200:
{
"valid": true,
"user": { "id": "lx_8c1e…", "name": "Alex Rivera", "username": "alexr",
"picture": "…", "email": "alex@example.com", "email_verified": true },
"nonce": "b41f…",
"expires_at": "2026-11-14T21:10:00.000Z"
}
Anything else answers 400 with "valid": false, an error code and a plain message (see Errors). Then compare the nonce with the one the page sent you, and sign the person in.
PHP
<?php
$in = json_decode(file_get_contents('php://input'), true);
$ch = curl_init('https://sensorium.events/api/signin/verify');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['token' => $in['token'] ?? '', 'client_id' => 'YOUR_CLIENT_ID']),
CURLOPT_TIMEOUT => 10,
]);
$check = json_decode(curl_exec($ch), true);
curl_close($ch);
if (empty($check['valid']) || ($check['nonce'] ?? null) !== ($in['nonce'] ?? null)) {
http_response_code(401);
exit;
}
$person = $check['user']; // id, name, username, picture, email, email_verified
// Find your account by $person['id']; create or link one if there is none.
session_regenerate_id(true);
$_SESSION['linxi_id'] = $person['id'];
Node.js
app.post('/auth/linxi', express.json(), async (req, res) => {
const r = await fetch('https://sensorium.events/api/signin/verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token: req.body.token, client_id: 'YOUR_CLIENT_ID' })
});
const check = await r.json();
if (!check.valid || check.nonce !== req.body.nonce) return res.sendStatus(401);
// check.user.id is this person's permanent ID on your website.
req.session.linxiId = check.user.id;
res.sendStatus(204);
});
Python
import requests
check = requests.post('https://sensorium.events/api/signin/verify',
json={'token': token, 'client_id': 'YOUR_CLIENT_ID'}, timeout=10).json()
if not check.get('valid') or check.get('nonce') != nonce:
abort(401)
person = check['user']
Or check it yourself with the public key
The pass is a standard signed token (JWT, RS256). If you would rather not call Sensorium Events on each sign-in, check it with any JWT library against the public key at https://sensorium.events/.well-known/linxi-signin-keys.json (a JWKS; it is also at /api/signin/keys). Then confirm:
issishttps://sensorium.eventsaudis your client IDexphas not passednonceis the one your page sent- you have not accepted this
jtibefore (keep the ones you have seen for ten minutes)
The person's details are in sub (their ID), name, preferred_username, picture, email and email_verified. Checking it yourself cannot tell you when someone has disconnected your website; the check above can.
Linking to your own accounts
- Use
idas the link. Store it against your account the first time, and look people up by it after that. - Match an existing account by email only when
email_verifiedistrue. An unconfirmed email could be anyone's. - When there is no match, either create an account from the details, or ask “Already have an account here? Sign in once to link it.” and store the
idafterwards. - Emails and usernames can change. Update your copy from each new sign-in; never use them as the link.
Button options
Set these on the script tag (for every button) or on a single data-linxi-signin element (for that one):
| Attribute | Values | What it does |
|---|---|---|
data-client | your client ID | Required, on the script tag. |
data-callback | a function name | Called with { token, user, nonce }. |
data-theme | light (default), dark, auto | auto follows the visitor's light or dark setting. |
data-size | large (default), small | 44 or 36 pixels tall. |
data-shape | rect (default), pill | Rounded corners or fully round ends. |
data-text | signin (default), continue, signup | “Sign in with”, “Continue with” or “Sign up with” Sensorium Events. |
data-mode | popup (default), redirect | See Redirect mode. |
data-redirect | a registered page | Where redirect mode comes back to. |
data-prompt | consent | Always show the approval screen, even to someone who approved before (useful for “switch account”). |
How they look:
Redirect mode
Some pages cannot open small windows (some in-app browsers, or a site that blocks them). With data-mode="redirect" the whole page goes to Sensorium Events and comes back to a registered return page (an admin adds these beside your addresses). The script on that page picks up the answer, fires the same callback and event, and removes it from the address bar. The pass travels after a #, so it never reaches your server's logs; send it to your server exactly as in popup mode.
JavaScript
The script also gives you window.LinxiSignIn:
// Start a sign-in yourself (call it from a click, so the window may open):
myButton.addEventListener('click', async () => {
try {
const { token, user, nonce } = await LinxiSignIn.signIn();
} catch (err) {
console.log(err.code, err.message); // e.g. "closed", "popup_blocked"
}
});
// Draw a button into an element added later:
LinxiSignIn.render(document.querySelector('#later'), { theme: 'dark' });
Errors
In the page (linxi:signin-error, or a rejected signIn()):
| Code | Meaning |
|---|---|
closed | The person closed the window before finishing. |
cancelled | The person pressed Cancel. |
popup_blocked | The browser blocked the window. Start the sign-in from a click, or use redirect mode. |
no_client | The script tag has no data-client. |
state_mismatch | A redirect came back to a page that did not start it. |
From the check on your server ("valid": false):
| Code | Meaning |
|---|---|
invalid_token | Not a pass Sensorium Events signed, or not one it knows. |
wrong_site | The pass was given to another website (a different client ID). |
expired | Older than ten minutes. Ask the person to sign in again. |
already_used | This pass was checked before. |
disconnected | The person disconnected your website. |
site_off | Signing in on your website is switched off. |
unknown_site | The client ID is not registered. |
account_blocked | That account may not sign in to other websites. |
Security checklist
- Check every pass on your server (the check, or the public key) before signing anyone in.
- Compare the
noncewith the one your page sent. - Link accounts by
id, and by email only when it is confirmed. - Start a new session for the person after signing them in (for example
session_regenerate_idin PHP). - Register only the addresses you really use. The window hands a sign-in back to those addresses and no other.
When people disconnect
Everyone sees the websites they have signed in to in Account → Connected sites, with what each one sees, and can disconnect any of them. After that, your website's next sign-in asks them again, and any pass not yet checked fails with disconnected. Their account on your website is yours to keep or remove; Sensorium Events does not reach into it.
Troubleshooting
- “This sign-in was started from an address the website has not registered.” The page's address (scheme, host and port) is not in your list.
www.example.comandexample.comare different addresses; register both if people use both. - Nothing happens after approving. If your site sends
Cross-Origin-Opener-Policy: same-origin, the small window cannot report back. Usesame-origin-allow-popups, or redirect mode. - The window is blocked. Browsers allow it only from a click. If you call
LinxiSignIn.signIn()yourself, call it directly inside the click handler. - Trying it locally. Ask for
http://localhost:3000(your port) to be added to your website's addresses.