= Tokens
:description: Your two credentials as a service owner: a personal access token for ulabase and CI, and a fifteen-minute admin token for a test by hand.
:keywords: personal access token, admin token, CI credentials, API token, ulabase login, service admin JWT
:group: Your users
:order: 30

As a service owner you have two kinds of token. A **personal access token** lets xref:cli.adoc[`ulabase`] and your CI jobs act on your services. An **admin token** lasts fifteen minutes, and is for trying a request by hand.

You find both on one page: **your profile, Tokens** (https://ulabase.com/me/tokens).

These tokens are yours, as the owner. Your app's users are the service's own xref:managing-users.adoc[users], with credentials of their own.

image::/assets/docs-images/tokens.png[The Tokens page: a form to create a personal access token, and the list of existing ones with when each was last used]

== Which one you need

[cols="1,2,2"]
|===
| | 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
|===

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 [[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 [[it-carries-the-cli-role-not-yours]]

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 xref:cli.adoc[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 [[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 xref:change-streams.adoc#authentication[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 xref:managing-users.adoc[Users].