Access control
Four kinds of access reach an account: a dashboard session with a role, an API key with scopes, an Admin Portal invite session, and one narrow product role. This page says what each can reach.
| Access | Held by | Scoped to | What it can reach |
|---|---|---|---|
| Dashboard session with a role | A dashboard user | The accounts the user belongs to | Reads and writes by role: viewer, member or admin. RealmSSO reads the role from the database on each request. |
| API key with scopes | Your integration | One account | The scopes the key carries. RealmSSO checks scopes on each route that accepts a key. |
| Admin Portal invite session | Your customer’s IT admin | One account | The Admin Portal for that account, for 30 minutes after RealmSSO makes the invite link. |
| Product-IdP-admin row | A dashboard user, for one product | One product, and one named account for each call | One read: the product handout. |
Dashboard session: account membership and role
A dashboard user reaches an account through an account membership. The membership has a role: viewer, member or admin. The roles rank viewer < member < admin. A route that needs member also admits admin.
RealmSSO checks the role on every account-scoped dashboard route. It reads the role from the database on each request, not from the token. A stored role with any other name is refused. The dashboard user who creates an account becomes its admin.
| Role | What it can do |
|---|---|
viewer | Read only. A viewer can use every account-scoped read route. That includes the audit log. |
member | Every write that is not admin only. That includes deleting the account and creating an invite link for an IT admin. |
admin | Everything a member can do. Only an account admin can set the connection-error policy (POST /api/v1/accounts/:id/connection-error-policy) and manage API keys: create (POST /api/v1/api-keys), change (PATCH /api/v1/api-keys/:id) and delete (DELETE /api/v1/api-keys/:id). |
No route manages members
No route adds a member, removes one or changes a role. The only membership that the API writes is the one that makes the creator of an account its admin. A viewer or a member exists only through a direct database change today. This page does not promise a team-management feature.
API keys: scoped, hashed and bound to one account
An API key belongs to one account. RealmSSO creates it as ss_ followed by 64 hex characters and shows it once. RealmSSO stores only a SHA-256 hash and an 8-character prefix. Your application sends the key in the X-API-Key header.
By default a key has the scope * and no expiry. The scope * means all account-scoped scopes.
A key has no role. RealmSSO does not map a key onto a membership. The authority of a key is the account it belongs to and the scopes it carries. A key can never create a key, and it can never hold platform operator authority.
Scopes are checked on every route that accepts a key
RealmSSO checks scopes on each route that accepts an API key. A dashboard session carries no scopes, and the scope check does not apply to it.
| Scope | What it allows |
|---|---|
connections:read, connections:write, connections:delete | Read, create and change, and delete connections and sign-in settings. |
agent-clients:read, agent-clients:write | Read agent clients. Register and revoke them. |
webhooks:read | Read webhooks and their deliveries. |
webhooks:write | Create, change and delete webhooks. Test and redeliver also need this scope, because each sends a request out. |
observability:read | Read sign-in events and connection health. |
audit:read | Read the audit log. |
platform:accounts:create | Create an account. A platform-level key can hold only this scope. The scope * does not include it. |
* | All account-scoped scopes. |
A platform-level key belongs to no account. A platform operator creates it. It can hold only platform:accounts:create, and it lasts 90 days at most.
Admin Portal: invite sessions for IT admins
Your customer's IT admin does not need an account. A dashboard user creates an invite link for one account and one email address. RealmSSO stores only a hash of the link's token. The link works once and lasts 30 minutes.
The IT admin presents the token in the X-Admin-Token header. A continuation session then keeps the portal working. The whole session ends 30 minutes after RealmSSO made the link.
The link is a bearer credential. Whoever holds it within 30 minutes acts as the IT admin. The dashboard user who creates the link also gets the full link in the response.
An invite session reaches only the Admin Portal routes of its one account. With it, the IT admin can:
- read the account's connections, with their secrets removed
- create a SAML or OIDC connection
- replace the settings of a SAML or OIDC connection
- set the account's SCIM settings, including the SCIM token
It cannot delete a connection, read the audit log or reach any other route. The portal's screens set up SAML, turn SCIM on and set the SCIM token. The portal's OIDC screen does not work today. The session can still create an OIDC connection through the portal's routes.
The audit log records the IT admin by email address, with the actor type customer_admin. See Admin Portal and Invite links. For the audit log, see Audit log.
Product-IdP-admin: one read, and nothing else
A dashboard user can hold a product-IdP-admin row for one product. The row unlocks exactly one read: GET /api/v1/products/:id/handout for one named account. It allows no write, no provisioning and no secret read. The row does not work for a dashboard user who belongs to any account. RealmSSO checks this when a platform operator grants the row, and on each request. See Identity Gateway.
Platform operator
A platform operator is RealmSSO staff. This authority is separate from the four kinds of access above. Only a platform operator can register products, create product grants and read across accounts.
A database row marks the role, and it is set outside the API. No API key can hold the role.
For the headers, rate limit and session rules that apply to every kind of access, see Security overview.