Tokens

As a service owner you have two kinds of token, for different jobs. You find both on one page: your profile, Tokens (https://ulabase.com/me/tokens).

Neither is for your app’s users. They are the service’s own users, with credentials of their own.

The Tokens page: a form to create a personal access token

Which one you need

Personal access token Service admin token

	Personal access token	Service admin token
What it is for	The `ulabase` command line and CI pipelines	Calling one service’s API by hand: curl, a REST client, a quick script
Lasts	30 days to a year, until you revoke it	15 minutes
Reaches	Your services' configuration, through Ulabase	One service, with full administrator rights inside it
Cannot	Buy or cancel a service, change your account, manage your team	Touch Ulabase itself, or any other service
You keep it	In a secret store, or in `~/.config/ulabase`	Nowhere: generate one when you need it

What it is for

The ulabase command line and CI pipelines

Calling one service’s API by hand: curl, a REST client, a quick script

Lasts

30 days to a year, until you revoke it

15 minutes

Reaches

Your services' configuration, through Ulabase

One service, with full administrator rights inside it

Cannot

Buy or cancel a service, change your account, manage your team

Touch Ulabase itself, or any other service

You keep it

In a secret store, or in ~/.config/ulabase

Nowhere: generate one when you need it

In short: the personal token is long-lived and narrow, the service token is short-lived and wide. Use the first for automation, the second for calls by hand.

Personal access tokens

A personal access token authenticates you to Ulabase, so that a machine can manage your services on your behalf.

Your account password does not fit this job. If you signed up with Google or GitHub you have no password: the OAuth flow ends in an httpOnly cookie, which only a browser can use. And an account password reaches billing and every service you own; revoking it means changing it everywhere it is used.

It carries the `cli` role

A token carries the role cli, set by the server, whatever the roles of the person who issued it.

So it is deny-by-default. A permission written for user does not match a token whose only role is cli: a token reaches only what is granted to cli explicitly. A mistake in the grants makes a token that can do too little, never one that can do too much.

In practice a token can read the feature catalog, read and change feature configuration, run GraphQL queries, mint a service admin token for a service you own, and provision a free service. It cannot start a Stripe Checkout session, cancel a subscription, read invoices, change your account, or manage your team.

Tip	You cannot choose the role. Every token is issued with `cli`: letting the caller choose its own role would let anyone raise their own privileges.

Issuing and revoking

Give the token a name and an expiry, and copy it: the console shows its value only once. Ulabase stores only a hash, so a leaked database leaks no token. If you lose a token, revoke it and issue a new one.

The expiry is 30 days, 90 days (the default) or a year. Every token expires, so a forgotten one stops working on its own.

The list shows each token’s name, when it was created, when it expires and when it was last used. The last column tells you which tokens you no longer use.

Revoking takes effect within about a minute.

A token carries no team

Ulabase checks your team membership on every request. If you are removed from a team, your tokens stop working on that team’s services at once, with nothing to revoke.

For the same reason a token cannot pick a team for you: an operation that needs one names it in the request.

Using one

See The ulabase command line. In a pipeline, set ULABASE_TOKEN from your platform’s secret store; in a terminal, ulabase login stores it at ~/.config/ulabase/session.json, readable only by you.

Service admin tokens

A service admin token is a JWT that authenticates you to one service as its administrator. The console uses the same kind of token for every call it makes to your service.

It lasts 15 minutes, so there is nothing to store. Generate one, use it, let it expire.

You can get one from two places:

the service’s Home, as the Admin JWT, next to a ready-made request for that service;
the Tokens page, where you pick the service from a list.

Inside that service it can do anything an administrator can. Outside it, nothing: it gives no access to Ulabase or to your other services.

Note	A service admin token cannot authenticate a WebSocket change stream. Only users registered in the service’s own `users` collection can. See Change streams: authentication.

In practice

To set up a service from a terminal or a pipeline, use a personal access token, through ulabase.
For a one-off curl against a service you are exploring, use a service admin token.
An application your users sign in to uses neither: it uses your service’s own users, in its users collection. See Users.