= The root user
:nav-title: Root user
:description: Every service has a root user with the widest permission of the service. How to set its password, when to use the Admin JWT, and why your app signs in with its own users.
:keywords: root user, admin credentials, admin JWT, service password, reset password
:group: Get started
:order: 30

Every service comes with a user called `root`. Root starts with the widest permission of the service: it reads and writes any collection, and changes users, permissions and settings. It is a permission like the others, so you can change it. You set its password when you create the service.

You use root to set up and look after the service, from a terminal or a script. This page says how to set and reset its password, when the **Admin JWT** is the better choice, and why your app signs in with its own users.

== The password

To change it, on the service's **Home**, in the **Basic Auth** box, type a new password of at least 8 characters and click **Reset password**.

image::/assets/docs-images/connect-credentials.png[The service's Home, with the reset-password action under Basic Auth]

The console does not keep the password, so it cannot show it later. If you know it and want the console to use it in this session, type it and click **Use it**: it stays in the browser tab and is never sent to the server.

**Reset password** changes the password on the service. Anything that used the old one stops working until you update it.

== The Admin JWT

Next to Basic Auth is the **Admin JWT**: a token with administrator rights that lasts 15 minutes. Use it for a quick test from a terminal, without typing the password:

[source,bash]
----
curl -i https://c0ffee.ulabase.app/todos \
  -H "Authorization: Bearer <admin-jwt>"
----

When it expires, click **Refresh** for a new one. See xref:tokens.adoc[Tokens] for what this token can reach.

== What root is for

Use `root` to set the service up: create collections, users and permissions from a terminal or with xref:cli.adoc[`ulabase`], and check things by hand.

Your app never uses `root`. It signs in as one of the service's own users, each with the roles and permissions you grant. You need a user, created through xref:signup-mgmt.adoc[sign-up] or on the xref:managing-users.adoc[Users] page, and a permission on the xref:managing-permissions.adoc[Permissions] page. The console's **API Tutorial** does this in its last two steps.

== How root gets its powers

`root` holds the `root` role, and the service is created with the permission `rootCanDoEverything`, which grants that role every path of the service:

[source,json]
----
{
  "_id": "rootCanDoEverything",
  "roles": ["root"],
  "predicate": "path-prefix('/')",
  "priority": 0,
  "mongo": { "allowManagementRequests": true, "allowWriteMode": true }
}
----

You see it on the Permissions page, and you can change it like any other permission, for example to narrow it. Do not delete it: without it, nobody can administer the service.

== Do it from the command line

xref:cli.adoc[`ulabase`] does not need the root password. It signs in to the service with an Admin JWT, the token of the box above, which it asks for itself.

If you want the password of `root` in your pipeline's secrets, set it with a step:

[source,typescript]
----
import { defineSetup, step, fromEnv, resolveEnvRefs } from '@ulabase/cli';

export default defineSetup('Root', [
  step('root password is the one in ROOT_PASSWORD', {
    async check({ service }) {
      // try to sign in as root with the password in ROOT_PASSWORD: if it works, the password is already set
      const basic = Buffer.from(`root:${process.env.ROOT_PASSWORD}`).toString('base64');
      const res = await fetch(`${await service.url()}/users/root`, {
        headers: { Authorization: `Basic ${basic}` },
      });
      return res.ok;
    },
    apply: ({ service }) =>
      // set the new password; resolveEnvRefs() replaces fromEnv('ROOT_PASSWORD') with the value of that variable
      service.fetch('/users/root', {
        method: 'PATCH',
        body: JSON.stringify(resolveEnvRefs({ password: fromEnv('ROOT_PASSWORD') })),
      }),
  }),
]);
----

The check signs in as `root` with the password from the environment, so a second run changes nothing. The step changes only the password, as **Reset password** does.