> ## Documentation Index
> Fetch the complete documentation index at: https://docs.albus.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Install the CLI, sign in with a browser, or authenticate with an organization API key.

Authenticate a client against Albus. Albus accepts two credentials, and both are
sent as `Authorization: Bearer <value>`:

| Credential       | Who it identifies | Where it comes from                         |
| ---------------- | ----------------- | ------------------------------------------- |
| **User session** | You               | `albus login`, or signing in to the console |
| **API key**      | Your organization | `albus tokens create`, or the console       |

Sessions, secrets, agents, traces, memories, and models accept either, and so
does `/whoami`, which names whichever of the two signed the request. Operations
that act as *you* rather than as your organization — everything under `/tokens`,
and `/invites` — accept the user session only.

## Install the CLI

The CLI is the only way to sign in with a browser, and the fastest way to run a
session. It is a Python package and needs Python 3.11 or newer.

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl -fsSL https://albus.sh/install.sh | sh
  ```

  ```powershell Windows theme={null}
  irm https://albus.sh/install.ps1 | iex
  ```

  ```bash uv theme={null}
  uv tool install albus-cli
  ```

  ```bash pip theme={null}
  pip install --user albus-cli
  ```
</CodeGroup>

If `albus` is not found afterwards, the install directory — usually
`~/.local/bin` — is not on your `PATH`; open a new shell, or add it. The SDKs
install with `pip install albus-sdk` and `npm install @albus-ts/sdk`; see
[SDKs](/reference/sdks).

## Sign in with a browser

```bash theme={null}
albus login
albus whoami
albus logout
```

`albus login` opens your browser, listens on `127.0.0.1:8484-8487` for the
redirect, and stores the session in `$ALBUS_CONFIG_DIR/credentials.json`, else
`$XDG_CONFIG_HOME/albus/credentials.json`, else `~/.config/albus/`. It renews
itself as it expires.

When nothing should open a browser for you — a coding agent running the command,
or a shell where your browser is not the one Albus would launch — use
`--no-browser`. It prints the authorization URL and waits for you to open it:

```bash theme={null}
albus login --no-browser
```

The redirect comes back to `127.0.0.1:8484-8487` on the machine running the CLI,
so open the URL in a browser on that machine. From a remote host, forward those
four ports from your own machine first:

```bash theme={null}
ssh -L 8484:localhost:8484 -L 8485:localhost:8485 \
    -L 8486:localhost:8486 -L 8487:localhost:8487 user@remote-host
```

This is how a coding agent signs you in: it prints the URL, you click it. See
[Albus for coding agents](/agents/docs).

## Create an API key

An API key is organization-scoped, has no expiry, and is the right credential
for scripts, CI, and agent harnesses. Sign in first, since minting a key
identifies you.

```bash theme={null}
albus tokens create ci
```

```json theme={null}
{
  "id": "9pv2rk3n",
  "name": "ci",
  "token": "alb-9pv2rk3n-1f4c8a6b2d9e7c50a3b81df6",
  "created_at": "2026-02-10T18:03:44Z"
}
```

The token value has the form `alb-<id>-<secret>`. `id` is its first segment, and
is what `albus tokens get` and `albus tokens delete` take.

<Warning>
  The `token` value is returned **once**, at creation. `albus tokens list` and
  `albus tokens get` return metadata only. Store it in a secret manager, never in
  a repository.
</Warning>

The console shows the same thing at
[albus.sh/api-keys](https://albus.sh/api-keys). Revoke a key with
`albus tokens delete <id>`.

## Use an API key

<CodeGroup>
  ```bash CLI theme={null}
  export ALBUS_API_KEY="alb-9pv2rk3n-1f4c8a6b2d9e7c50a3b81df6"
  albus sessions list
  ```

  ```python Python theme={null}
  import os
  from albus_sdk import Albus

  with Albus(
      api_key=os.environ["ALBUS_API_KEY"],
  ) as albus:
      print(albus.sessions.list_sessions())
  ```

  ```typescript TypeScript theme={null}
  import { Albus } from "@albus-ts/sdk";

  const albus = new Albus({
    security: { apiKey: process.env.ALBUS_API_KEY ?? "" },
  });

  console.log(await albus.sessions.listSessions());
  ```

  ```bash cURL theme={null}
  curl --fail-with-body \
    --header "Authorization: Bearer $ALBUS_API_KEY" \
    https://albus.sh/api/sessions
  ```
</CodeGroup>

<Note>
  One variable name for every client: the CLI and both SDKs read `ALBUS_API_KEY`,
  and the SDKs also read `ALBUS_BEARER_AUTH` for a user token. Constructed with no
  credential, an SDK takes them from the environment; otherwise pass the key
  explicitly — `api_key=` in Python, `security: { apiKey }` in TypeScript.
</Note>

In the CLI, an exported `ALBUS_API_KEY` **wins over a stored session**, so an
agent or CI job never touches disk. `albus tokens` and `albus invites` are the
exception: they use the stored session even when a key is exported, because a key
cannot act as you. `albus whoami` follows the same precedence as everything else
and names whichever credential it sent.

## Point at another API

```bash theme={null}
albus --base-url http://localhost:8080/api sessions list
export ALBUS_BASE_URL=http://localhost:8080/api
```

`--base-url` overrides `ALBUS_BASE_URL`, which overrides the default
`https://albus.sh/api`. Credentials are stored per base URL, so signing in to
one does not sign you in to another.