Skip to content
CelestianCelestian Documentation

Platform admin console

The admin console lives at /admin and is used by the platform administrator (not a workspace admin) to manage user accounts. The admin account is not an ordinary user account: its credentials are in .env, its session is separate, and its pages are at /admin.

Enabling it

Section titled “Enabling it”

  1. Create a password hash (at least 12 characters; the password is not stored anywhere):

    Terminal window
    cd ~/celestian/deploy
    read -rs PW; printf '%s' "$PW" | docker compose run --rm --no-deps -T api hash-password; unset PW

  2. Copy the result into deploy/.env. The single quotes around the hash are required (the hash contains $; without quotes Compose corrupts it):

    Terminal window
    ADMIN_USERNAME=platform-admin
    ADMIN_PASSWORD_HASH='$argon2id$v=19$m=19456,t=2,p=1$…$…'
    ADMIN_SESSION_TTL=8h

  3. docker compose up -d, then open https://<domain>/admin and sign in. The api log records platform admin console active when the credentials are read; a broken hash makes api fail to start with a clear message.

Emptying one of the variables turns the console off. Changing ADMIN_USERNAME revokes all running admin sessions. Repeated wrong passwords lock that username temporarily.

Functions

Section titled “Functions”
Function Description
Account list Search, advanced filters (name, username, e-mail, ID, tag, status, full quota), sorting, and pagination.
Create user Name, username, e-mail, password, tags, and metadata. The e-mail is verified immediately (this can be turned off). The account gets the new-account default quota and a welcome e-mail with a sign-in link and a link to set a password.
Bulk create From a CSV (columns username*, first_name*, email*, last_name, password, tags, metadata_json), at most 200 rows, with a preview and all-or-nothing. An empty password = a random one nobody knows; the account is opened through the link in the welcome e-mail.
Account detail The Detail, Metadata, and Journals tabs.
Disable / enable A disabled account: sessions are revoked and sign-in is refused immediately; the workspaces and their data are unchanged.
Reset password Two modes: send a reset link to the account e-mail, or set a new password now (with an option for a generated random one, shown once). It can always revoke all sessions and clear the lockout.
Quota Change how many workspaces, devices, and channels an account may create. A number, 0 (may not create), or unlimited. Lowering a quota does not delete what already exists.
Make admin Only the main admin (from .env). That account signs in at /admin/login with its own account and can manage users and quotas, but cannot promote other admins.
Transfer owner Forcibly move a workspace’s owner to another member (the recipient’s quota is still checked).
Delete account Deletes the account and all workspaces it created, permanently. First transfer the owner of workspaces still used by other people. Messages in TimescaleDB are cleaned up gradually in the background.
Bulk delete Pick accounts and delete them; the impact per account is shown, and you type the number of accounts to confirm.
Export CSV The account list according to the filters (at most 20,000 rows, without password hashes).
Deleted workspaces A tab listing workspaces waiting for permanent deletion: Restore or Delete now.
History /admin/journal: all admin actions with filters and CSV download.

Quotas

Section titled “Quotas”

New accounts get DEFAULT_MAX_WORKSPACES, DEFAULT_MAX_DEVICES, and DEFAULT_MAX_CHANNELS (1/1/1 by default; -1 = unlimited). Accounts that existed before quotas remain unlimited.

  • A quota is counted over all workspaces created by that user. Devices and channels created by other members in those workspaces use the workspace owner’s allowance.
  • A gateway counts as a device.
  • When the limit is reached, creation (including a CSV import, which is cancelled entirely) is refused with a quota message.

Console security

Section titled “Console security”
  • The admin session uses a separate token (a different audience) without refresh; a user token does not pass admin endpoints and vice versa.
  • The celestian_admin cookie is httpOnly, sameSite=strict, and limited to the /admin path.
  • All actions are recorded in History with the actor admin.