Accounts API

All routes live under /api/v1/accounts and accept a dashboard session. Send it as Authorization: Bearer <token> or in the realmsso_token cookie. A route that names an account checks two things. The caller must belong to the account, and the caller must hold the role that the route needs. The role is viewer for the reads. The role is member to update or delete an account and to claim or verify a domain.

The list route names no account. It returns only the accounts that the caller belongs to. A caller with no membership on an account id gets 403. This includes an id that does not exist.

Roles rank viewer < member < admin, so an account admin passes every check on this page. See Access control. Accounts and isolation explains the realm that each account has.

One route also accepts an API key: POST /api/v1/accounts, the call that makes the first account. It takes a platform-level key. A platform-level key belongs to no account. A platform operator makes it. A platform operator is RealmSSO staff.

The key must hold the scope platform:accounts:create. The wildcard * does not replace that scope.

Every other route in this module refuses an API key with 401. RealmSSO checks this before it checks any scope or membership. So a platform-level key can create an account, but it cannot read, update or delete that account. For the routes on this page, later access needs a dashboard session with a membership on the account.

Create account

The response is 201 with the account in data. The caller becomes an admin member of the new account in the same database transaction. Without that, the creator would have no access to the new account. With a platform-level key, the person who made the key becomes the admin member, not the key.

After the transaction commits, RealmSSO creates the account's realm. A realm is the separate sign-in space of one account. It has its own users, clients, identity provider links and signing keys. The realm name is kr- followed by the account id. It does not contain the slug.

If realm creation fails, the response is still 201. The realm field in the table above is then null. RealmSSO creates the realm on the first request that needs it, for example the creation of a connection. A slug that exists returns 409. A domain that another account already holds also returns 409.

List accounts

Returns the accounts that the caller belongs to, not every account on the server. The list is paginated with ?page and ?limit (maximum 100). Each item includes a _count.connections field.

Get account

Returns the account and its connection count. A caller with no membership on the id gets 403.

Update account

Accepts a partial body of name, domain, logo and brandColor. Each one accepts null to clear it, except name. It does not change the realm. A new domain value runs the same claim logic as the claim route below. A new domain string never inherits the verified status of the old one.

Delete account

List the connections of an account

A summary route. It returns every connection of the account, without pagination. See Connections for the full connection routes: create, update, delete and check.

Claim a domain

Records an email domain for this account and issues a new DNS TXT challenge. The body is { "domain": "acme.com" }. The response is 202, not 200. RealmSSO stores the claim, but ownership is not yet verified.

Publish the returned TXT record at _realmsso-challenge.<domain>. Then call the verify route. Two accounts cannot hold the same domain. The check ignores letter case. A collision returns 409.

Verify a claimed domain

Checks the TXT challenge of the claimed domain against DNS now. On a match, it records the verification. No match is a normal 200 with verified: false, not an error, because DNS changes take time. You can call this route again and again.

Verification makes a domain usable for login routing. GET /api/v1/sso/resolve matches a verified domain only. It treats a claimed but unverified domain like a domain that nobody claimed. It gives one answer for an unknown domain, an unverified domain and a domain with no active connection: 200 with ssoAvailable: false. See Accounts and isolation.

Other routes in this module