Skip to content

Features

Identity and access

Who is signed in, what they may do, and how the first account comes to exist. This is CONTRACT.md Addendum v0.5 as services/rust/orbit-api implements it: local users, sessions, roles over a closed permission set, and an audit line for every change (see audit.md). People can also sign in through Google (Addendum v0.8) or any OpenID Connect provider (Addendum v0.19); see "Single sign-on".

Two credentials, two jobs

Every call into orbit-api carries two things, and they answer different questions.

CredentialWho holds itWhat it provesWhere it travels
Service bearer ORBIT_AUTH_TOKENweb's server onlyThe call came through web (Addendum v0.2)Authorization: Bearer ... on every proxied call
Session tokenThe browser, inside an HttpOnly cookieWhich person is askingCookie orbit_session from the browser to web; X-Orbit-Session from web to orbit-api

orbit-api checks the bearer first, then the session, then the one permission the route asks for. No session is 401 unauthorized; a session whose role lacks the permission is 403 forbidden, with the permission named in the message and an access.denied event in the audit trail. With ORBIT_AUTH_MODE=disabled (local demos only) there is no bearer to check, and the session is still verified.

Routes that answer without a session, the whole list (PUBLIC in services/rust/orbit-api/src/api.rs): GET /healthz, GET /readyz, GET /api/v1/auth/state, POST /api/v1/auth/login, POST /api/v1/auth/setup, POST /api/v1/contact, and the single sign-on pairs POST /api/v1/auth/sso/start and /callback (Google) and POST /api/v1/auth/sso/oidc/start and /callback. Every other route, including one nobody has written yet, needs a session. GET /api/v1/version and GET /api/v1/nocturne/models need a session and no permission.

On the browser side, a Deck page requested without the cookie is redirected to /login (/pt-BR/login in Portuguese) with ?next= set to the page, and the Deck layout checks the session again against orbit-api before it renders anything. A web server with no ORBIT_API_URL has no one to sign in: it serves the console as an anonymous read-only demo, with the permissions of the viewer role, and the admin pages say they need orbit-api.

The first admin

orbit-api creates the first account at startup, and only while no user exists. It tries three sources, in this order.

1. ORBIT_ADMIN_USER and ORBIT_ADMIN_PASSWORD_VERIFIER. Set both or neither: one without the other refuses to start. The verifier is the PBKDF2 string apps/web/scripts/hash-password.mjs prints, never the password itself:

bash
openssl rand -base64 24 > admin-password && chmod 600 admin-passwordORBIT_ADMIN_PASSWORD_VERIFIER="$(node apps/web/scripts/hash-password.mjs < admin-password)"

The script refuses anything under 15 characters and writes 600,000 iterations; orbit-api accepts a verifier of 210,000 iterations or more and refuses a malformed one at startup. The username must match [a-z0-9][a-z0-9._-]{0,31}. Where the two values go is install-path specific: the release Secret for Helm and plain manifests (install/helm.md, install/kubectl.md), .env for compose (install/docker-compose.md). The pair is read on every start and ignored once any user exists (the log says so); changing it later changes nothing.

2. The demo users, when ORBIT_DEMO_DATA=true and no admin pair is set: admin, editor and viewer, one per built-in role, sharing one password per install: ORBIT_DEMO_PASSWORD, which the Helm chart draws into its Secret at install, or a random one orbit-api draws when that is empty. orbit-api prints it once, in a WARN line with a demo_password field, at the start that creates the accounts; the login page lists the enabled ones without it. Read it back with kubectl -n sreorbit get secret sreorbit-secrets -o jsonpath='{.data.ORBIT_DEMO_PASSWORD}' | base64 -d on Helm, or docker compose logs orbit-api | grep demo_password on compose. An account an older release created with its public password gets this one at the next start. They exist to demo the roles; they are ordinary accounts once created, so a data directory that started on demo data keeps them even after ORBIT_DEMO_DATA turns false. Delete them, or start production on an empty data directory.

3. A one-time setup code, when neither applies (a live install with no admin pair). orbit-api logs it once at startup, as a WARN line with a setup_code field:

bash
kubectl -n sreorbit logs deploy/sreorbit-orbit-api | grep setup_code

On compose, docker compose --project-name sreorbit --env-file .env -f deploy/compose/docker-compose.yml logs orbit-api | grep setup_code. Open /login: while no user exists it offers "create the first admin", which takes that code, a username, a name and a password, creates the account with the admin role and signs you in. The code is 12 characters in groups of four (dashes and spaces are ignored when you type it), lives only in the process's memory and dies with it: a restart before the admin exists prints a new one, and once the admin exists there is no code at all. Five wrong codes from one address start a wait that doubles up to 15 minutes. The same step from a shell, against orbit-api port-forwarded as in "Signing in from a shell" below, with setup.json holding setupCode, username, name and password:

bash
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H 'content-type: application/json' \  --data @setup.json localhost:8080/api/v1/auth/setup

It answers 201 with the new user, 401 for a wrong code and 409 once any user exists.

Signing in

In a browser: /login. From a shell, write the credentials to a file only you can read (printf is a shell builtin, so the password never shows up in ps):

bash
umask 077printf '{"username":"%s","password":"%s"}\n' admin 'REPLACE_WITH_THE_PASSWORD' > login.json

Replace REPLACE_WITH_THE_PASSWORD with the password of that account: the contents of admin-password for the env admin, the install's demo password for a demo user, or the one typed at setup. A password holding " or \ needs JSON escaping.

Signing in from a shell

Through web, the way the browser does it. web's route sets the cookie and strips the token from the body, so keep a cookie jar. When web's own Basic auth is on (the chart's default; see security.md), add -u "admin:$(cat web-password)" to both calls, where admin is the WEB_AUTH_USER you put in the Secret and web-password the file you hashed into WEB_AUTH_VERIFIER. YOUR_REAL_HOSTNAME is your ingress.host:

bash
curl -fsS -c orbit.cookies -H 'content-type: application/json' --data @login.json \  https://YOUR_REAL_HOSTNAME/api/v1/auth/logincurl -fsS -b orbit.cookies https://YOUR_REAL_HOSTNAME/api/v1/auth/me

Directly against orbit-api, for scripts and agents inside the cluster: the login answer carries the token, and every later call sends it as X-Orbit-Session beside the bearer:

bash
kubectl -n sreorbit port-forward svc/sreorbit-orbit-api 8080:8080 &SESSION="$(curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H 'content-type: application/json' \  --data @login.json localhost:8080/api/v1/auth/login | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')"curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" localhost:8080/api/v1/auth/me

$ORBIT_AUTH_TOKEN is the bearer you generated at install time; on the k3d loop read it from the release Secret, as install/local-k3d.md shows.

What a refusal means

AnswerWhy
401 unauthorizedWrong username or password. The message is the same for an unknown username, and a sign-in takes as long either way, so a refusal does not reveal which accounts exist.
403 forbiddenThe password was right and the account is disabled.
429 rate_limited + Retry-AfterA wait is running. Nothing is checked until it ends.
401 mfa_requiredThe password was right and the account signs in with a code too: send it as code. Nothing is counted.
401 mfa_wrongThe code was wrong or already used. Counts as a failed sign-in.

Failures are counted per username and per client address before any password is checked. A username gets 5 free failures, then a wait that starts at 1 s and doubles up to 1 minute; a client address gets 20, then up to 15 minutes. The address budget applies only when an edge proxy named the client (see "How the client IP is determined" in audit.md); without one every visitor arrives from web's address and only the username budget holds, so one visitor cannot lock everyone else out. On top of that the sign-in routes allow 30 requests a minute per named client, and 300 a minute shared by all unattributed ones. A correct sign-in clears the username's count, 30 minutes without a failure forgets it, and a restart of orbit-api forgets every count.

Two-step sign-in

A role that holds users.manage or settings.manage signs in with a password and a 6-digit code from an authenticator app (TOTP, RFC 6238: HMAC-SHA1, 30-second steps, the codes 1Password, Bitwarden, Google Authenticator and Authy show). Any other account may turn it on too. A demo account never has it: everyone who reads the demo password shares it.

  • Enrolling. The first time such an account signs in with its password, the Deck opens /login/secure and nothing else: orbit-api answers that session 403 mfa_enrollment_required everywhere but GET /api/v1/auth/me, sign-out and the two calls below. POST /api/v1/auth/mfa/setup draws a new 20-byte key and answers it once, in base32 and as an otpauth:// link. POST /api/v1/auth/mfa/confirm with {"code":"123456"} turns it on: this session counts as one that gave a code, and every other session of the account ends. A role that gains one of the two permissions later gets the same page at its next request.
  • Signing in. With a second factor on, POST /api/v1/auth/login takes code beside username and password. Without it, a right password answers 401 mfa_required and counts as nothing; a wrong code, or one already used, answers 401 mfa_wrong and counts as a failed sign-in for the username and the address, so codes cannot be guessed faster than passwords. A code works once: orbit-api keeps the last time step it took.
  • Losing the phone. An admin turns it off from PATCH /api/v1/users/{id} with {"mfa": false} (audited as user.mfa_reset); every session of that account ends, and its next sign-in enrolls again. The subset rule applies: you reset only an account whose role holds nothing yours lacks. Turning off your own needs your password and a code (see Passwords below).
  • The key at rest. orbit-api seals it with ORBIT_SEAL_KEY (AES-256-GCM, the same sealing as database and SSO secrets) when that key is set, and stores it as typed otherwise. The chart draws ORBIT_SEAL_KEY at install when secrets.sealKey is empty and keeps the one its live Secret holds on every upgrade, so a default install seals every key. A key stored as typed before the install had ORBIT_SEAL_KEY gets sealed at the first start with one. It never leaves the store after the setup answer and never reaches the audit trail. Keep ORBIT_SEAL_KEY with your other secrets and back it up: under another key, or with none, a sealed key no longer reads, and every account with a second factor gets 401 at sign-in, admins included. Setting the old key back restores them. If it is lost, an account that still signs in with users.manage turns the others' factor off; plan one such account (an SSO admin, whose sign-in needs no local factor) before you rotate the key.
  • SSO sessions bring the identity provider's own factors: Google and OIDC sign-ins skip this step. Require MFA at the provider.
  • API tokens of an account whose role needs the second factor work only once it is on, or when the account signs in through SSO.
  • Rollback. A release before this one ignores the key and signs the account in with the password alone; it drops the key the first time it rewrites that user, so the account enrolls again after you upgrade back.

Single sign-on

People can also sign in through an identity provider; the local username and password stay for the emergency admin. Each provider is off until an admin configures it at Admin > Integrations (settings.manage) or the environment seeds it, and /login shows its button only while it can sign someone in. Google is Addendum v0.8: one Workspace, its domains, one role for a first sign-in. The rest of this section is the generic provider of Addendum v0.19.

Any OpenID Connect provider

One provider at a time, beside Google: Okta, Microsoft Entra ID, Keycloak, Auth0, or any other that publishes a discovery document. What the admin sets:

SettingDefaultNotes
Issuer URLnonehttps only, no query, fragment or credentials. orbit-api reads <issuer>/.well-known/openid-configuration, follows no redirect, and refuses a document whose issuer is not this exact string (Auth0's ends in /, Entra ID's in /v2.0).
Client ID and secretnoneA confidential web client on the authorization code flow. The secret is write-only: no read answers it, and the audit trail records only that it changed.
Scopesopenid email profileopenid is required. Add the scope your provider sends groups for (groups on Okta).
Button nameSSO"Sign in with" this name on /login; the audit trail names the provider by it.
Allowed email domainsanyWhen set, the email's domain must be on the list.
Email claimemailA top-level claim holding the address. When the ID token carries email_verified, it must be true; without it the person can still get a new account, but no existing account is linked to them.
Groups claimgroupsA top-level list of strings (a single string works too).
Group to rolenoneOrdered rows: the first row whose group the person is in gives the role, admin included, as long as the admin saving the settings holds every permission of that role.
Role when no group mapsviewerA role that manages neither users nor settings, or deny, which refuses the sign-in.

Register https://<your console>/api/v1/auth/sso/oidc/callback as the redirect URI (the settings page prints it with the host you reached it on). Run Test before turning the provider on: it reads the discovery document and the signing keys, then tries the client ID and secret at the token endpoint with a code that cannot exist, so invalid_grant proves the credentials. A test saves nothing. The stored secret goes only to the stored issuer for the stored client ID: to test another issuer or client, type its secret. Every test writes settings.test to the audit trail with the issuer, the client ID and each check's result.

The flow. web's GET /api/v1/auth/sso/oidc/start asks orbit-api to open a flow (state, nonce and a PKCE S256 verifier, good once for 10 minutes), keeps its binding in the same HttpOnly cookie the Google flow uses and sends the browser to the provider. The provider returns to /api/v1/auth/sso/oidc/callback; web hands the state, the binding and the code to orbit-api, which redeems the code with the verifier (client_secret_post when discovery lists it, client_secret_basic otherwise) and checks the ID token:

  • signed RS256, PS256 or ES256 by a key in the provider's JWKS, never none or an HMAC; RSA keys of 2048 bits or more, EC keys on P-256, and a key the JWKS pins to one algorithm is used for that one only;
  • the JWKS is read with a 1 MiB cap and a 10 s timeout and cached for its max-age (5 minutes to a day); an unknown kid fetches it again at most every 30 s, so a key rotation is picked up and a flood of invented kids is not;
  • iss exactly the configured issuer; aud holds the client ID, and azp must be the client ID when there are several audiences or whenever it is present;
  • exp, nbf and iat within 60 s of skew and issued during the flow; the nonce the flow's own;
  • then the email, email_verified, the domain and the groups, as in the table.

Accounts. The account linked to the provider's subject (sso: "oidc:<sub>") signs in; failing that, the one local account with the email (ASCII case ignored, not a demo account, not linked to another provider) is linked, but only when the ID token says email_verified: true (email_unverified otherwise) and the account holder set that email, or saved it, with their password and a code. An email another admin typed into someone's account links nothing (email_unproven) until its holder saves it with that proof from their own drawer on /deck/admin/users. Failing that, a new account is created, its username taken from the email's local part. With a group mapping, the role it gives is written onto the account at every sign-in: a group removed at the provider takes the role away at the next one, and a user.role_change event records it. Without a mapping, the default role applies to new accounts only and admins change roles in the Deck, as with Google. A role change that would leave no enabled user holding users.manage refuses the sign-in instead (last_admin). The settings remember the permissions of the admin who saved them, and no sign-in through them lands on an account whose role holds more (beyond_provider): someone who manages settings but not everything cannot point the console at an identity provider of their own and sign in as an admin. Settings saved before this rule, and the environment seed, carry no such limit. The session is the ordinary one: 24 hours, revocable.

Refusals and the trail. Each sign-in writes auth.login with method: "oidc", the provider's name, the issuer and the role. Each refusal writes auth.login_failed with the same fields and a reason: invalid_state, expired, off, cancelled, provider_error, exchange_failed, invalid_token (with the check that failed: format, algorithm, key, signature, issuer, audience, expired, not_before, issued_at, nonce or subject), unavailable, no_email, email_unverified, domain_not_allowed, no_group, disabled, or an account conflict (linked_elsewhere, ambiguous_email, email_unproven, demo_account, role_missing, default_role_missing, default_role_unsafe, last_admin, beyond_provider). A refused person lands on /login?oidc=<why>, told in their language. The two routes are counted in orbit_http_requests_total, by status, under POST /api/v1/auth/sso/oidc/start and POST /api/v1/auth/sso/oidc/callback.

Seeding it from the environment. While the store holds no OIDC settings, orbit-api reads ORBIT_SSO_OIDC_* (configuration.md); from the first save in the console on, the console's settings win. The client secret belongs in the Secret (secrets.ssoOidcClientSecret in the chart). A client secret saved in the console, for OIDC or Google, sits in the store sealed with ORBIT_SEAL_KEY (AES-256-GCM, the key the database connections use) when that variable is set; one an earlier release kept in the clear gets sealed at the next save of its page. Without ORBIT_SEAL_KEY the store keeps it as typed. If you change the key, sign-in through that provider stops until an admin types the secret again. The same happens after a rollback to a release without sealing: it sends the sealed text as the secret, so type the secret again on the provider's page after you roll back. A save that changes the issuer or the client ID takes the client secret again: the stored one only ever goes to the issuer and client it was typed for. To read what is in effect, with an admin's SESSION from "Signing in from a shell":

bash
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \  localhost:8080/api/v1/settings/sso/oidc

Passwords

orbit-api stores a PBKDF2-HMAC-SHA256 verifier for every password it sets: 600,000 iterations, a 16-byte random salt, a 32-byte hash, the same format as web's own WEB_AUTH_VERIFIER. A new password needs at least 12 characters, at most 128, no control characters, must not equal the username, and must not be one of the 10,000 passwords of 12 characters or more leaked most often (SecLists tag 2025.3, case ignored). There are no composition rules and no expiry. Sign-in still accepts up to 1,024 bytes, so a longer password set earlier keeps working.

  • Your own password: the Account page (/deck/account), or POST /api/v1/auth/password with {current, next}. A wrong current is 400, and counts as a failed sign-in for your username. Every other session of yours ends; this one stays.
  • Someone else's: an admin sets a new one from the user's drawer on /deck/admin/users, or PATCH /api/v1/users/{id} with password. Every session of that user ends.
  • Your own through PATCH /api/v1/users/{id} on your own id, with password or {"mfa": false}: send your password as current, and with a second factor on, a fresh code too. Without them, or with a wrong one, orbit-api answers 400 (mfa_required or mfa_wrong for the code), counts a failed sign-in for your username and audits the refusal. Someone who stole your session cannot set a password and a key of their own and lock you out. Every other session of yours ends; this one stays.
  • Your own email through the same route takes the same proof: SSO links an account by its email, so a stolen session could otherwise point your account at an address the thief holds at the provider. A missing password answers 400 and costs no attempt. An email an admin sets on someone else's account is saved, and SSO does not link that account by it until the holder saves it with their password and a code.
  • After a proof (your password and a code here, for a token, or a sign-in again at the provider) the same session needs none for 5 minutes.
  • Each of these changes, on any account, posts a security notice to the alert channels that take them (alert-notifications.md).
  • A password an admin typed, when creating a user or resetting someone else's, is a first password only: its next sign-in lands on /login/secure and changes it before anything else (orbit-api answers 403 password_change_required to everything else). Then a role that needs it enrolls its second factor.
  • A password set before it made the leaked list still signs in, and lands on the same page.
  • Every new-password field in the Deck shows a strength meter as you type. It is a rough guess from length and character mix; orbit-api's rules above decide.

Sessions

  • Token. A 32-hex-digit session id and an HMAC-SHA256 signature over it. A forged or altered token is refused before anything is looked up. The key is ORBIT_SESSION_SECRET when set (32 bytes or more); otherwise orbit-api generates a 32-byte key once and keeps it in ORBIT_DATA_DIR/session.key. Changing the secret or deleting the file ends every session at once.
  • Lifetime. 24 hours from sign-in, absolute: activity does not extend it. A session that no request used for 8 hours ends too, and its next request is 401. An open Deck tab keeps reading only while the browser lets it run: a tab it freezes, or a laptop asleep, counts as no request. A restart of orbit-api starts every idle clock again. A user keeps at most 100 sessions; the oldest go first. Expired ones are swept at most every 10 minutes.
  • Revocation. A session is also a document under ORBIT_DATA_DIR/sessions, deleted on logout, on disable, on a password change or reset, and by "End all sessions" (POST /api/v1/users/{id}/revoke-sessions). The next request with that token is 401. A password change or reset, and a second factor turned off, also delete every API token of the account (see mcp.md).
  • Your own sessions. Account, "Your sessions" lists every browser signed in to your account (GET /api/v1/auth/sessions: when it signed in, from which address and browser, when it ends, and which one is this browser). Typing your password there signs out the others (POST /api/v1/auth/sessions/end-others, metered like a sign-in and audited as auth.sessions_end_others). A demo account sees only its own session and ends none. An account Google or OIDC created has no password: the page offers "Sign in again with Google" (or your provider's name) instead. The session that sign-in starts signs the others out without a password for 5 minutes, and only when the provider's id_token says in auth_time that you signed in there after you clicked, a minute of clock skew allowed. With an older auth_time, or none, you get an ordinary session, and the page says the provider did not confirm it asked for your credentials. "Change password" says the account has no password instead of showing a form it cannot use. For OIDC, orbit-api sends prompt=login and max_age=0. The first asks the provider for your credentials; the second makes auth_time a required claim (OpenID Connect Core 3.1.2.1). Google takes no reauthentication request: its sign-in may reuse the Google session your browser already has, and then auth_time is old. Google sends auth_time only when the request asks for it, which orbit-api does with claims={"id_token":{"auth_time":{"essential":true}}}, and only when "Session age claims" is on in Google Auth Platform, Settings, Advanced settings (the app must be in production and verified). Without that setting, a Google account without a password cannot sign its other sessions out; an admin can, with "End all sessions". To get a fresh auth_time, sign out of your Google account in that browser first, then sign in again.
  • Role changes. The permissions are read from the user's role on every request, so a role change, or an edit of the role itself, applies to the next request, without a new sign-in.
  • The cookie. __Host-orbit_session when the browser is on https (X-Forwarded-Proto, or an https publicUrl, which outranks that header: see configuration.md), with Secure and no Domain, and orbit_session on plain http; HttpOnly, SameSite=Lax, Path=/, and a Max-Age equal to the session's remaining lifetime. Only web's two routes api/v1/auth/login and api/v1/auth/logout write it; page JavaScript cannot read it. web copies its value into X-Orbit-Session and never forwards the browser's Cookie header.

Your data

Account, "Your data", downloads what orbit-api keeps about you as one JSON file (GET /api/v1/auth/export, audited as user.export): your account, your sessions, your API tokens' names and expiry, the saved views, SQL queries and Nocturne chats you own, and the audit events you caused in the last 90 days, at most 1,000. It holds no password verifier, second factor key, token secret or webhook. A demo account is shared and exports nothing (403). To remove your data, delete your views, queries and chats where you made them; an admin deletes the account itself.

Roles and permissions

A user holds exactly one role, and a role is a set of permissions from this closed list. Each route asks for one of them; the Deck hides the sections a role does not grant and refuses them before the page reads anything.

PermissionGrantsDeck section
estate.readClusters, nodes, workloads, events, alerts, FinOps, recommendations, workload events, and Nocturne's read routes/deck and everything under it not listed below
telemetry.queryquery_range, the engine's label, series and instant reads, Nocturne's PromQL tool/deck/observability, /deck/explore, every dashboard panel
apm.readTraces, services, operations and the service map/deck/apm
logs.readContainer logs of a workload's pods, and the stored logsThe logs tab of a workload, /deck/logs
databases.queryDatabase monitoring and read-only SQL on the database connections the role reaches (/api/v1/databases, POST /api/v1/sql/query and /explain with a database)/deck/databases, /deck/sql
databases.raw_sqlWith databases.query: a monitored statement's recent runs with their values, each reveal audited"Show values" in a statement's drawer
dashboards.readListing and opening dashboards/deck/dashboards
dashboards.writeCreating, changing and deleting saved dashboardsEdit and Save on a dashboard
nocturne.usePOST /api/v1/nocturne/chat and /analyze/deck/nocturne
workloads.writeScale and resources writes, CronJob suspend, resume and run now, alert acknowledgements and silences, never in orbit-api's own namespace or kube-systemThe Scale and resources tab
config.readA workload's environment against its ConfigMaps and Secrets, and revealing one masked value, never in orbit-api's own namespace; Nocturne's ConfigMap tool, the env values in its pods tool and the values its patch check diffs (without it, each variable shows its name and source and the value [redacted]); every view and every reveal is auditedThe Configuration tab of a workload
users.manageUsers, roles, the sales leads list/deck/admin, /deck/admin/users, /deck/admin/roles, /deck/admin/leads
audit.readThe audit trail and its CSV export/deck/admin/audit
settings.manageThe console's settings page, the ingestion rules, and the AWS account's bill on the FinOps overview/deck/settings, /deck/admin/ingestion

workloads.write is necessary and not sufficient: a scale or resources change also needs the deployment to allow writes (ORBIT_WRITE_ENABLED=true with the write ClusterRole, Addendum v0.4) and the operator token on web's hop. Opening a dashboard needs dashboards.read, and drawing its panels needs telemetry.query as well: a role with the first and not the second sees the layout with every panel refused.

Built-in roles

RolePermissions
viewerestate.read, telemetry.query, apm.read, logs.read, dashboards.read
editorEverything viewer has, plus dashboards.write, nocturne.use and workloads.write
adminEvery permission in the list

Built-in roles live in the binary: nothing in the data directory can change them, and an edit or a delete is 400. For another set, create a custom role (or clone a built-in one in the Deck and edit the copy).

Custom roles and the rules that protect an install

  • A custom role has a name (1 to 64 characters, unique), a description of up to 280 characters, and any subset of the permissions above; an unknown permission is 400.
  • A custom role may list the database connections its databases.query reaches (databases, up to 64 connection ids); none listed is every connection. Outside the list a connection answers 404 on every database route. See databases.md, "A role for a database team".
  • A role that any user holds cannot be deleted (409): move its users first.
  • Nobody changes their own role, disables their own account or deletes it (400).
  • Nobody grants more than they hold. Creating or editing a role, giving a user a role, and changing, resetting, disabling, deleting or ending the sessions of an account all need the actor's own role to hold every permission involved; otherwise the answer is 403 and an access.denied event with reason: "subset". With the built-in roles only admin manages users, so nothing changes; a custom role with users.manage manages only the accounts and roles it outranks. The same rule applies to the roles an SSO setting gives, and to database connections: an actor whose role lists some grants and touches only roles that list some of the same.
  • No change may leave zero enabled users who hold users.manage: a disable, a delete, a role change or an edit of a role that would do so is 409.

Managing users and roles

In the Deck, with users.manage: /deck/admin/users creates users, changes roles, resets passwords, disables, enables and deletes accounts and ends sessions; /deck/admin/roles creates, edits, clones and deletes custom roles and shows the full permission matrix. From a shell, with the SESSION of an admin from "Signing in from a shell" above: list the roles, create a user, promote them, end their sessions.

bash
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" localhost:8080/api/v1/rolescurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -H 'content-type: application/json' \  -d '{"username":"grace","name":"Grace Hopper","email":"grace@example.com","role":"viewer","password":"REPLACE_WITH_AN_INITIAL_PASSWORD","current":"REPLACE_WITH_YOUR_PASSWORD","code":"CODE"}' \  localhost:8080/api/v1/userscurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -H 'content-type: application/json' \  -X PATCH -d '{"role":"editor","current":"REPLACE_WITH_YOUR_PASSWORD","code":"CODE"}' localhost:8080/api/v1/users/USER_IDcurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -X POST \  localhost:8080/api/v1/users/USER_ID/revoke-sessions

Creating a user, and setting another account's password, second factor, email or role, take your own password as current and, with a second factor on, a code: without them the answer is 400, audited as a refusal under your name. One proof covers the same session for 5 minutes. Saving the Google or OIDC settings takes the same proof: a provider lets people in. Name, disable, delete and ending sessions take none: they only take access away. REPLACE_WITH_YOUR_PASSWORD and CODE are yours, typed again.

REPLACE_WITH_AN_INITIAL_PASSWORD is a password you choose for the new user (12 characters or more, not the username) and hand over on a channel you trust. USER_ID is the id field of that user in the answer to the create call, or in GET /api/v1/users (16 hex digits), not the username. Every shape and error of these routes is in api.md; every change above lands in the audit trail named by what changed (user.role_change, user.disable, user.password_reset, ...).

Where the state lives

Everything on this page is files under ORBIT_DATA_DIR (default /var/lib/sreorbit), one JSON document per object, each written to a temporary file, fsynced and renamed into place, so a crash leaves the old version or the new one and never half of either:

PathHolds
users/One document per user, with the password verifier
roles/Custom roles (built-in ones are in the binary)
sessions/One document per live session
dashboards/Saved dashboards (dashboards.md)
alertstate/Alert acknowledgements and silences, one document per cluster
leads/Submissions of the site's contact form
settings/Sign-in settings: sso for Google, oidc for the OpenID Connect provider, secrets included
audit/The audit trail, one JSONL file per UTC day (audit.md)
changes/The change timeline, one JSONL file per cluster and UTC day, 14 days (audit.md)
changestate/What the change timeline's last tick saw, one document per cluster
session.keyThe session signing key, when ORBIT_SESSION_SECRET is not set

orbit-api refuses to start when the directory is not writable. The store has one writer, which is why every install path runs orbit-api as one replica: the chart renders replicas: 1 whatever replicaCount says and refuses to render with autoscaling on (components.orbit-api.singleWriter). With components.orbit-api.persistence.enabled the directory is a ReadWriteOnce claim and the Deployment uses Recreate; without it, an emptyDir that loses every user, session, dashboard and audit line with the pod. Compose mounts the named volume orbit-api-data. Backups: operations.md.

Nocturne acts as the signed-in user

When someone asks Nocturne a question, orbit-api's proxy passes their X-Orbit-Session through to nocturne, and every cluster tool call Nocturne makes carries it back to orbit-api. A tool therefore reads exactly what that person may read (its PromQL tool needs telemetry.query, the rest estate.read), and a refusal lands in the audit trail under their name.

Ceilings

  • One OpenID Connect provider at a time, beside Google; no SAML. The groups must be a top-level claim of the ID token: Entra ID's group overage (past 200 groups it sends a link instead) is not followed. ORBIT_AUTH_MODE=oidc, which is about the service bearer and not about people, still refuses to start.
  • TOTP is the only local second factor. No WebAuthn or FIDO keys and no recovery codes: a lost phone is an admin reset. No SCIM, no password expiry.
  • One replica. The file store has one writer; the upgrade path named in the source is Postgres, which is what lets orbit-api scale out.
  • Sign-in waits are per process. A restart of orbit-api forgets them, which a single replica can live with.
  • No per-dashboard or per-cluster scoping. A permission applies to every cluster and every saved dashboard.

Where to go next

  • What every change and refusal leaves behind, and how to read it: audit.md.
  • The threat model around sessions, cookies and cross-site requests: security.md.
  • Every variable on this page with its default: configuration.md.