> ## 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.

# Authenticate

> Sign in with a browser, or authenticate with an organization API key.

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.

## 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` 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](/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": "…",
  "name": "ci",
  "token": "alb-…",
  "created_at": "…"
}
```

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

  ```python Python theme={null}
  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())
  ```

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

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

  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>
  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.
</Note>

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

```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.