Authenticate

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, and agents accept either. Operations that identify you rather than your organization — /whoami and everything under /tokens — accept the user session only.

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 on the machine running the CLI, so open the URL in a browser on that machine. From a remote host, forward the ports first (ssh -L 8484:localhost:8484 …). 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": "…",
  "name": "ci",
  "token": "alb-…",
  "created_at": "…"
}

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-…"
albus sessions list

import os
from albus_sdk import Albus, models

with Albus(
    security=models.Security(api_key_auth=os.environ["ALBUS_API_KEY_AUTH"]),
) as albus:
    print(albus.sessions.list_sessions())

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

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

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

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

The variable names differ by client: the CLI reads ALBUS_API_KEY, and the SDKs read ALBUS_API_KEY_AUTH (or ALBUS_BEARER_AUTH for a user token) when you construct the client with no explicit security. Export both, or pass the key explicitly.

In the CLI, an exported ALBUS_API_KEY wins over a stored session, so an agent or CI job never touches disk. albus whoami and albus tokens are the exception: they use the stored session even when a key is exported, because a key cannot identify you.

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

For coding agents

Alpha

Reference

API reference

Create an API key

Use an API key

Point at another API

​Sign in with a browser

​Create an API key

​Use an API key

​Point at another API

Sign in with a browser

Create an API key

Use an API key

Point at another API