Documentation
Orion ID is a standard OpenID Connect provider: any OIDC library works.
Sign in with Orion ID (OpenID Connect)
- Register your app in My apps. It starts in development mode: only you can sign in with it.
- Set up your OIDC library with the discovery document:
https://oriondatagroup.com/.well-known/openid-configuration - Redirect to
https://oriondatagroup.com/oauth/authorizewithresponse_type=code,client_id,redirect_uri(exact),scope=openid profile,state,nonceand PKCE (code_challenge+code_challenge_method=S256, required for all apps). - Exchange the
codeatPOST https://oriondatagroup.com/oauth/tokenwithgrant_type=authorization_code,code_verifierandredirect_uri. Confidential apps authenticate withclient_secret_basicorclient_secret_post. - Validate the
id_token(RS256): signature with the JWKS (https://oriondatagroup.com/.well-known/jwks.json, pick the key bykid),iss,aud= your client_id,expandnonce. - Use
subas the person’s identifier. It’s stable and reveals nothing.
GET https://oriondatagroup.com/oauth/authorize?response_type=code&client_id=oid_…&redirect_uri=https%3A%2F%2Ftuweb.com%2Fcallback
&scope=openid%20profile&state=…&nonce=…&code_challenge=…&code_challenge_method=S256
POST https://oriondatagroup.com/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=…&redirect_uri=…&client_id=oid_…&code_verifier=…
200 {"token_type":"Bearer","expires_in":900,"access_token":"eyJ…","refresh_token":"def…","id_token":"eyJ…"}
Access tokens: 15 min. Refresh tokens: 30 days, single use (each refresh returns a new one; reusing an old one revokes that app’s whole session). Revocation: POST https://oriondatagroup.com/oauth/revoke (RFC 7009). prompt=none|login|consent are supported.
Complete, runnable example: examples/demo-client in the repository.
Permissions (scopes)
| Scope | What it grants | Requires approval |
|---|---|---|
openid | Confirm it’s you (anonymous, stable identifier) | No |
profile | Your @username, display name and photo | No |
links | The networks and website of your card | No |
email | Your verified email address | No |
organizations | The companies you belong to and your role in each | Yes, per app |
The password is never shared. The e-mail and the networks only arrive if the person accepts on the permission screen.
What you receive
GET https://oriondatagroup.com/oauth/userinfo Authorization: Bearer eyJ…
{"sub": "01JB…", "preferred_username": "lucia", "name": "Lucía", "picture": "https://oriondatagroup.com/avatars/lucia?v=…",
"profile": "https://oriondatagroup.com/@lucia", // only if their card is public
"orion_links": {"instagram": "https://instagram.com/lucia", "web": "https://lucia.example"}, // scope links
"email": "lucia@example.com", "email_verified": true} // scope email
The same data, as plain JSON, at GET https://oriondatagroup.com/api/v1/me. In the id_token, amr says how the person signed in (mca = approved on their phone or by QR, otp = code, hwk = passkey) and acr is orion:mfa when there was a second step. To require it, send acr_values=orion:mfa.
Ecosystem: single sign-in, sign out everywhere and messages
What makes several websites feel like one. It works with any app; what is marked «of the group» only with the websites Orion ID marks that way.
Signing in without a click
When someone arrives without a session, redirect to /oauth/authorize with prompt=none. If they already have Orion ID open and had accepted your website, they come back at once with a code; if not, they come back with error=login_required and you show your «Continue with Orion ID» button. Websites of the group asking only for openid profile email links show no permission screen: the person goes straight in (the permission is listed in «Your websites» and can be removed).
Sign out
Close your session and send the person to https://oriondatagroup.com/oauth/logout with client_id, post_logout_redirect_uri and state. Orion ID asks whether to sign out of Orion ID too or of every website, and sends them back to post_logout_redirect_uri, which must be on the same website (https and same domain) as one of your return addresses.
If they choose «everywhere» (or press «Sign out of every website» in Security), each website receives the session.ended webhook with their sub: close all of that person's sessions on your website.
Messages in Notifications
Your website can leave a notice in the Orion ID account of a person who uses it: an order shipped, a reply, a reminder of theirs. It reaches «Notifications» and, if they have it on, their phone. Plain text only; the link must be on your website.
POST https://oriondatagroup.com/api/v1/messages
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
{"sub": "01JB…", "title": "Order shipped", "text": "Your order 1042 ships today.", "url": "https://tuweb.com/pedidos/1042", "id": "pedido-1042-enviado"}
201 {"data": {"delivered": true, "duplicate": false}}
idis optional: if you repeat the same one, nothing is duplicated (answers 200 with"duplicate": true).- Only to people who have signed in to your website with Orion ID and not removed its access (otherwise
404 not_found). Each person can mute your website in «Your websites» (403 messages_muted): stop sending to them. - Limits: 20 messages a day per person and 600 an hour for the whole website (
429 rate_limited). Use it for what the person would want to know, not for advertising: a website that abuses it loses access.
The group's websites
https://oriondatagroup.com/.well-known/orion-group.json lists the group's websites (name, address, description, logo and where to sign in). It is public and can be read from the browser: use it for a «More from the group» menu.
Webhooks
Set an https address on your app’s page and we’ll notify you of these events with a JSON POST request:
authorization.revoked: Someone revokes your app’s access (or the platform revokes it).account.deleted: Someone who used your app deletes their Orion ID account.account.updated: A person who uses your app changes their name, photo, e-mail or card (ask /oauth/userinfo again).account.secured: A person presses “It wasn't me”: close their sessions in your app and ask them to sign in again.session.ended: A person signs out everywhere from Orion ID: close their session on your website too.ping: test sent from the portal.
Account events only include the person’s sub identifier:
{"id": "evt_01jb…", "type": "authorization.revoked", "created": 1760000000, "client_id": "oid_…", "data": {"sub": "…"}}
- Signature. Header
Orion-Signature: t=…,v1=…: HMAC-SHA256 oft + "." + bodywith your signing key. Compare in constant time. - Replays. Reject timestamps older than 5 minutes. Each event has a stable
id(also in theOrion-Deliveryheader): retries and manual redeliveries repeat it, so store the processed ones and ignore duplicates by responding 200. - Delivery. Respond with 2xx in under 5 seconds (queue heavy work). Otherwise we retry after 1 min, 5 min, 30 min and 2 h. From your app’s page you can redeliver an event from the last 7 days.
- Network. HTTPS only, ports 443 or 8443, no redirects and no private addresses. We connect to the IP we checked, without resolving the domain again.
On your app’s page, Check integration sends three test requests with "test": true (a valid one, one with a forged signature and a stale one) and tells you whether your server accepts only the valid one.
Examples with common libraries
Always use a maintained OpenID Connect library: it validates the id_token, state and nonce for you. In the examples, ISSUER is https://oriondatagroup.com.
Node.js · openid-client
import { Issuer, generators } from 'openid-client';
const orion = await Issuer.discover(ISSUER);
const client = new orion.Client({ client_id: 'oid_…', client_secret: 'kius_…', redirect_uris: ['https://tuweb.com/callback'], response_types: ['code'] });
// /login
const code_verifier = generators.codeVerifier();
const state = generators.state(), nonce = generators.nonce();
req.session.oidc = { code_verifier, state, nonce };
res.redirect(client.authorizationUrl({ scope: 'openid profile', state, nonce,
code_challenge: generators.codeChallenge(code_verifier), code_challenge_method: 'S256' }));
// /callback
const tokens = await client.callback('https://tuweb.com/callback', client.callbackParams(req), req.session.oidc);
const { sub, acr, amr } = tokens.claims(); // sub: identificador estable de la persona
Python · Authlib (Flask)
from authlib.integrations.flask_client import OAuth
oauth = OAuth(app)
oauth.register('orion', server_metadata_url=ISSUER + '/.well-known/openid-configuration',
client_id='oid_…', client_secret='kius_…',
client_kwargs={'scope': 'openid profile', 'code_challenge_method': 'S256'})
@app.route('/login')
def login():
return oauth.orion.authorize_redirect(url_for('callback', _external=True))
@app.route('/callback')
def callback():
token = oauth.orion.authorize_access_token() # valida state, nonce y firma
person = token['userinfo'] # person['sub'], person['acr']
PHP · jumbojett/openid-connect-php
$oidc = new Jumbojett\OpenIDConnectClient(ISSUER, 'oid_…', 'kius_…');
$oidc->setRedirectURL('https://tuweb.com/callback');
$oidc->setCodeChallengeMethod('S256');
$oidc->addScope(['profile']);
$oidc->authenticate(); // redirige y, a la vuelta, valida el id_token
$sub = $oidc->getVerifiedClaims('sub');
Verify a webhook
// Node.js (Express): usa el cuerpo sin procesar
app.post('/orion/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const sig = Object.fromEntries((req.get('Orion-Signature') || '').split(',').map(p => p.split('=')));
const expected = crypto.createHmac('sha256', SECRET).update(`${sig.t}.${req.body}`).digest('hex');
const valid = sig.v1?.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig.v1), Buffer.from(expected));
if (!valid || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return res.sendStatus(400);
const event = JSON.parse(req.body);
if (alreadyProcessed(event.id)) return res.sendStatus(200);
queue.add(event); res.sendStatus(200);
});
# Python
def valid(header: str, body: bytes, secret: str) -> bool:
p = dict(part.split('=', 1) for part in header.split(','))
expected = hmac.new(secret.encode(), p['t'].encode() + b'.' + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, p.get('v1', '')) and abs(time.time() - int(p['t'])) <= 300
Complete dependency-free PHP example (sign-in, two-step, refresh, revocation and webhook receiver): examples/demo-client in the repository.
Errors and limits
{"error": {"code": "insufficient_scope", "message": "El token no tiene los permisos necesarios.", "details": {"required": ["openid"]}}}
Codes: validation_failed (422), invalid_token / unauthenticated (401), insufficient_scope / forbidden (403), not_found (404), rate_limited (429, with Retry-After), server_error (500).
Limits for /api/v1/me: 120 requests/min per app and person. Headers X-RateLimit-Limit and X-RateLimit-Remaining.
Versions and changes
- Without notice, we may add endpoints, optional fields in responses, new values in open lists (for example, webhook event types you explicitly subscribe to) and headers. Your code must ignore anything it doesn’t recognize.
- Breaking changes (removing or renaming fields, changing types or meanings, tightening validation) only ship in a new version:
/api/v2. Never within/api/v1. - Deprecation. A version is supported for at least 12 months after we announce its deprecation. During that period, responses carry the
DeprecationandSunsetheaders (RFC 8594) and we email everyone with active apps. - Orion ID follows OpenID Connect: the discovery document is the source of truth. Signing keys rotate with overlap; always select by
kidand fetch the JWKS again if you can’t find a match. - Security. A change needed to fix a security flaw may be applied without a notice period; we’ll explain it on the status page.
Service status and notices: https://oriondatagroup.com/status.
Required best practices
- Always validate
stateandnonce. Use PKCE with S256. - Keep the client secret on your server only. Mobile apps and SPAs must be registered as public (no secret).
- Redirect URLs are matched exactly. HTTPS only (or http://localhost in development).
- Don’t store access tokens in localStorage; prefer session cookies from your backend.
- When someone revokes access, your tokens stop working instantly: treat a 401 as “session ended”.