Docs menu

Tokens: Server and App

An access token lets another computer, a person or an AI tool use Secretbase on this computer, from anywhere. A token has one of two levels: an App token works only on the apps you choose, a Server token on every app. Give the smallest one that does the job.

Which one to make

  • An AI tool or a person working on one app: an App token for that app.
  • Someone who makes and runs their own apps here: an App token, co-developer.
  • An AI tool that runs every app: a Server token limited to deploy.
  • Your own laptop, to run the whole server: a Server token limited to admin.
  • Full control of Secretbase itself, from anywhere: a Server token with full control.

App tokens

$ secretbase tokens create --name client --app my-app
App: my-app, deploy. Can: Everything on its apps. Ends: <date>.

Access token "client" (shown only now: copy it somewhere safe):

  sbt_…

…
Revoke it any time with: secretbase tokens revoke client

It reaches only the apps you name (repeat --app for more). To it, your other apps don't exist. On its apps it can do everything: publish, undo, take offline and online, keys, database, logs, backups and restore, its domains, make it smaller (not bigger) and delete it. It doesn't ask you first. Add --scope read for a token that only looks.

A co-developer token, secretbase tokens create --name <name> --codev, makes its own apps and fully runs them, and never sees yours. --apps <N> and --memory <size> limit how many apps and how much memory. Revoking it ends the app tokens it made; its apps stay, yours.

Server tokens

A limited Server token reaches every app, but not Secretbase's own settings:

$ secretbase tokens create --name laptop --server --limit admin
Server, limited to admin on <machine>. Can: Everything but approvals. Ends: <date>.
…
  • --limit read: sees your apps, not their logs or visitors.
  • --limit deploy (recommended): also publishes, reads logs, undoes, takes apps offline, sets keys, turns databases on and off, reads the database, backs up and restores. Before it deletes an app or makes a new app public, it asks you first.
  • --limit admin: everything a token can do, without asking.

A Server token with full control, secretbase tokens create --name <name> --server, can do everything you can do here, from anywhere: addresses, backups, machines and tokens too. It is made only on the computer itself (at its keyboard or over SSH, or on its own dashboard), never by a token. Add --ask-first before you give it to an AI tool: it then asks you first before it deletes an app or backups, makes a new app public from an AI tool, or changes front doors, machines, the dashboard's name or the recovery key. Keep it like a master key.

How long a token lasts

--expires 1d, 7d, 30d or 90d. Without it, a token lasts 90 days, and a Server token with full control 30 days. never is only for a Server token limited to admin or with full control.

See and revoke tokens

$ secretbase tokens
…
App
NAME    ACCESS               CAN                     LAST USED  ENDS
client  App: my-app, deploy  Everything on its apps  Not yet    <date>
…
$ secretbase tokens revoke client
Token "client" is revoked: it no longer works anywhere.

secretbase tokens lists the tokens under Server and App, never the tokens themselves. Revoking a Server token with full control also stops the tokens it made. On the dashboard: AI tools, Access tokens, New access token, then Server or App?.

Good to know

  • The token is shown once. Keep it in a password manager.
  • Make tokens as yourself, not with sudo. A computer has at most 20 tokens.
  • Server, full-control and co-developer tokens are the server admin's: only the user who installed Secretbase there makes them. Others in the secretbase group make App tokens for their own apps, and see and revoke only theirs. The 1.0.13 update revoked the ones others had made before, and listed them: for the admin (and a full-control token), secretbase status and the dashboard say how many until you dismiss it (secretbase tokens revoked --dismiss, or Dismiss on the dashboard), secretbase tokens revoked lists each one's name, what it was, its scope and who made it, and one alert email carried the same list. On a server installed as root it revokes none and says so: install again with sudo from your own account to become its admin. If another user runs that install, the earlier installer's own tokens are kept.

If something goes wrong

  • "This access token is wrong or was revoked.": make a new one.
  • "This access token expired on <date>.": make a new one.
  • "This token's scope is <scope>; this needs <needed>.": make a token with that limit.
  • "This token can only work on <apps>.": it is an App token; make one for that app.
  • "Full control can only be made on the computer itself.": make it there.
  • "Too many wrong tries from your address. Wait 15 minutes and try again."