Invite links

An invite link gives your customer's IT admin access to the Admin Portal for one account. The link works once and lasts 30 minutes. The link is a bearer credential. Whoever holds it within those 30 minutes acts as the IT admin. RealmSSO does not check who opens it.

At a glance

Making the link

The call needs a dashboard session. RealmSSO then does these steps:

1. It generates 48 random bytes and hex-encodes them into the raw token.
2. It stores a SHA-256 hash of the token on a new session record. The record also holds the account ID, the IT admin's email, the display name and the expiry time. The expiry is 30 minutes from now.
3. It builds the link and tries to email it to the IT admin.

{
  "data": {
    "sessionId": "clx5a9d3f0007mnop",
    "portalUrl": "<portal host>/portal?token=<96 hex characters>&org=<account slug>",
    "expiresAt": "2026-10-07T14:30:00.000Z",
    "email": "it-admin@customer.test",
    "emailSent": true
  }
}

The call returns 201. portalUrl is the working link. It holds the raw token, so handle the response as a credential. RealmSSO never stores the raw token. It cannot show the link again, so make a new link if you lose it.

emailSent says whether the email went out. If the send fails, the call still returns 201, emailSent is false, and the link works. Give portalUrl to the IT admin another way. The audit record admin_portal.link_generated also records emailSent, with severity warn when the send fails. It never holds the link.

Using the link

The portal reads ?token= from the address and calls the route below. The token travels in the X-Admin-Token header. The server reads the token from that header only. It does not accept the token as a query parameter.

Authentication runs in two phases.

1. Bootstrap. The server hashes the token and consumes it in one conditional write. The write sets usedAt only where the hash matches, usedAt is still empty, and the expiry is in the future. Exactly one request wins. Every later presentation of the token matches no record. The first request that carries the token consumes it, on any route.
2. Continuation. The bootstrap token is now spent. The same response returns a continuation token, a signed token of kind admin-portal-session. It arrives three ways: an httpOnly cookie named realmsso_admin_session, an x-admin-session response header, and, on GET /session, the field data.continuation. Later requests send it back as the X-Admin-Session header or as that cookie.

The continuation token keeps the session alive. It never extends the session past 30 minutes from when the link was made. The server checks the link's expiry on every request. A late opener needs a new link.

A successful GET /session returns the account's name, slug, logo and accent colour. It also returns the IT admin's email and display name, and the time the session ends. A spent token that comes with a valid continuation token passes. A normal portal client sends the spent token on every call. A spent or expired token with no valid continuation gets 401.

What the link allows

The session covers one account. Inside it, the IT admin can list the account's connections and change the SCIM settings. The IT admin can also create or replace SAML and OIDC connections. The IT admin has no dashboard access and no other account. The portal screen does less than these routes allow. For example, the portal's OIDC tab does not call the OIDC routes below, so it does not save. See Admin Portal.

# The invite link
<portal host>/portal?token=<96 hex characters>&org=<account slug>

# First request: bootstrap. It consumes the token and returns the continuation
# token in an x-admin-session response header and a realmsso_admin_session cookie.
GET  /api/v1/admin-portal/session               X-Admin-Token: <raw token>

# Every later request: either header works, or the cookie
GET  /api/v1/admin-portal/connections           X-Admin-Session: <continuation token>
POST /api/v1/admin-portal/connections/saml      X-Admin-Session: <continuation token>
POST /api/v1/admin-portal/connections/oidc      X-Admin-Session: <continuation token>
PUT  /api/v1/admin-portal/connections/:id/saml  X-Admin-Session: <continuation token>
PUT  /api/v1/admin-portal/connections/:id/oidc  X-Admin-Session: <continuation token>
PUT  /api/v1/admin-portal/connections/:id/scim  X-Admin-Session: <continuation token>

What RealmSSO records

• Making a link. The audit record admin_portal.link_generated holds the email, the display name and emailSent.
• A portal sign-in. A sign-in event, not an audit record. The first use records a login.success event. A spent or expired token sent with no continuation token records a login.failure event. Its reason is already_used or expired. See Monitoring and health.
• Limits. Audit writes are best effort. See the Audit log page.

The sign-in link is a different thing

A dashboard user signs in with a sign-in link. It is not an invite link. It uses the same token pattern, with a shorter life.