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

# Identity and access

> Who can sign in to an outpost, what each role may do, and how programs and peers are let in.

## How sign-in works

Each outpost signs people in through one OpenID Connect provider: the built-in one, set up when you create the first administrator, or an external provider you point it at. The console keeps a session cookie that lasts 12 hours. The SDK and other clients send the provider’s ID token or an API key as a bearer; the terminal does the same after a `--device` or `--token` sign-in and keeps a session cookie after a password sign-in. Admission is re-read on every request, so a block or a role change applies at once.

The sign-in screen shows **Email** and **Password** where password sign-in is on, and otherwise one button: **Continue with single sign-on**, or **Sign in with Microsoft** when the provider is a Microsoft tenant. An account that was handed a temporary password chooses its own on first sign-in. **Settings → Account** shows your callsign, email and role, changes a password the outpost made, and signs you out.

## The first administrator

The first `drkm start`, or `drkm setup`, asks how the outpost signs people in: create the administrator with a password, or use an OIDC provider by issuer URL, client ID and client secret, with the outpost’s `/auth/callback` registered at the provider. `drkm setup --file` reads the answers from a private JSON file for unattended installs. The installer itself creates no accounts.

```bash Terminal theme={null}
drkm setup
drkm setup --file /path/to/identity.json
```

> [!NOTE]
>
> drkm start --profile development creates shared, well-known test accounts. Never use it on an outpost that a network can reach.

## Roles

Roles are a ladder: each one can do everything below it.

| Role | Can |
| - | - |
| **Viewer** | Read conversations and files, see skills, connections and the fleet. |
| **Analyst** | Send messages and manage conversations, upload files and edit skills, submit and manage jobs. |
| **Operator** | Everything an Analyst can, plus `drkm.broom` sweeps that read an outpost's files or run their own Python code. |
| **Admin** | Manage users and access, configure the outpost, its models and connections, read audit logs, see everyone’s jobs and spend. |

Everyone else sees their own jobs and the conversations they own or joined. The bootstrap administrator is always an administrator and cannot be blocked, and the last administrator cannot be demoted.

## Add people

**Settings → Users** has tabs for **Active**, **Invited**, **Blocked** and **Access**. Where the outpost makes its own accounts, **Add user** takes an email and a role and gives you a temporary password to hand over; with an external provider, **Invite user** records the email and role and you share the sign-in link. No email is sent either way. A member’s row changes their role, blocks or restores them, and resets a password the outpost made. Blocking keeps their conversations.

Under **Access**, **Who can sign in** is either *Invited users only* or *Anyone in the identity provider* with a default role that is never Admin. Changes apply on the next request.

## API keys for programs

**Settings → Keys → API keys** lets programs outside the console use the outpost’s API. **New key** takes a name, a role and an expiry of 30, 90 or 365 days or never; the secret, `drkm_ak_…`, is shown once. Each key is its own account with the role you chose: it owns what it creates, never counts as the last administrator, and even with the Admin role cannot manage users or keys. **Revoke** refuses the key on its next request.

```bash Use a key theme={null}
curl -H "Authorization: Bearer drkm_ak_..." https://outpost.example/users/me

# The SDK and the terminal read the same key from the environment
DRKM_URL=https://outpost.example DRKM_TOKEN=drkm_ak_... drkm console jobs
```

## Sign in from the terminal

`drkm console login` signs a terminal in with `--device` (a code to confirm in a browser), `--password` where the outpost allows it, or `--token` with an ID token minted out of band. `whoami` prints your email and role; `logout` drops the stored session. Store credentials in the OS keyring. On hosts without a keyring, have your secret manager inject `DRKM_TOKEN` at runtime; do not save credentials in files. Credentials never follow a redirect.

```bash Terminal theme={null}
drkm console login https://outpost.example --device
drkm console whoami
drkm console logout
```

## Audit and usage

Every privileged act, from an invitation or a role change to a connector save, a key removal, a model served or an update started, is recorded in the same transaction that performs it, in a log that is never edited. Administrators read it at `GET /audit`. Metered spend lands in a usage ledger at `GET /usage`: you read your own, an administrator reads the whole outpost, and `/usage` in the terminal workspace or `drkm console usage` prints a range.

```bash Terminal theme={null}
drkm console usage --range 30d

curl -H "Authorization: Bearer $DRKM_TOKEN" "https://outpost.example/audit?limit=50"
```

## Access between outposts

People and programs are admitted per outpost; outposts are admitted per mesh. Only administrators enroll outposts, mint invitations or change addresses, and an invitation is single-use and expires after 24 hours. Once enrolled, a peer acts under its own identity on the agent-to-agent API and job attempts; it never inherits a person’s role, and revoking its enrollment revokes that access. Every outpost serves HTTPS only; that certificate authenticates the service, not the user. See [adding devices to the mesh](https://docs.drkm.dev/mesh.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.