Authentication

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.

curl -fsSL https://albus.sh/install.sh | sh

irm https://albus.sh/install.ps1 | iex

uv tool install albus-cli

pip install --user albus-cli

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.

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:

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:

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.

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.

albus tokens create ci

{
  "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.

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.

The console shows the same thing at albus.sh/api-keys. Revoke a key with albus tokens delete <id>.

Use an API key

export ALBUS_API_KEY="alb-9pv2rk3n-1f4c8a6b2d9e7c50a3b81df6"
albus sessions list

import os
from albus_sdk import Albus

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

import { Albus } from "@albus-ts/sdk";

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

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

curl --fail-with-body \
  --header "Authorization: Bearer $ALBUS_API_KEY" \
  https://albus.sh/api/sessions

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.

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

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.

Getting started

Guides

Reference

API reference

Install the CLI

Create an API key

Use an API key

Point at another API

​Install the CLI

​Sign in with a browser

​Create an API key

​Use an API key

​Point at another API

Install the CLI

Sign in with a browser

Create an API key

Use an API key

Point at another API