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

# Authentication and roles

> Create bearer credentials and apply least-privilege roles to the Lookout HTTP interface.

> For the complete documentation index, see [llms.txt](https://devlookout.com/llms.txt). Markdown versions are available by appending `.md` to page URLs.

Every versioned HTTP request requires an authenticated principal in production. The exception is `GET /health`, which returns aggregate health only. Loopback administration is available only when `server.allowLoopbackAdmin` is enabled.

## Create a bearer credential

```sh theme={null}
lookout api-token-generate integration-reader viewer
```

The command returns:

* `token`, the one-time plaintext bearer token to put in a secret manager
* `credential`, the principal ID, SHA-256 token hash, and assigned role to put in the credential registry

An owner-only credential registry has this shape:

```json theme={null}
{
  "credentials": [
    {
      "id": "integration-reader",
      "tokenHash": "64-character-sha256-hex-digest",
      "roles": ["viewer"]
    }
  ]
}
```

Set `auth.credentialsFile` to its path. On Unix-like systems, both the containing directory and file must be inaccessible to other users.

## Send a request

```sh theme={null}
curl --fail --silent \
  --header "Authorization: Bearer $LOOKOUT_API_TOKEN" \
  https://lookout.example.com/api/v1/graph
```

<Warning>
  Do not place bearer tokens in URLs, command history, process arguments, JSON configuration, source control, or logs. Prefer a secret manager or owner-only file.
</Warning>

## Roles

| Role         | Capabilities                                                              |
| ------------ | ------------------------------------------------------------------------- |
| `console`    | Read the raw-log-free console projection only                             |
| `viewer`     | Read health, graph, detection plans, rules, events, Alerts, and Incidents |
| `ingestor`   | Ingest normalized and raw records                                         |
| `collector`  | Submit signed collector envelopes                                         |
| `analyst`    | Viewer access plus Alert review and Incident promotion                    |
| `rule_admin` | Read graph and detection state, then import rules                         |
| `admin`      | All permissions                                                           |

Use a dedicated credential per integration. Collector credentials can also be bound to one collector identity so a valid bearer token cannot submit an envelope for another collector.

## Credential lifecycle

* Add an optional ISO 8601 `expiresAt` value when generating or storing a credential.
* Set `disabled` to `true` to revoke access without deleting the audit identity.
* Rotate by creating a new token, updating the consumer, and then disabling the old credential.
* Requests with invalid, expired, or disabled credentials return `401`.
* Valid principals without the required permission receive `403`.

Every authenticated `/api/v1` request records a normalized access event and a separate API audit record. Sources outside `server.approvedSourceAddresses` are marked `unapproved_device` for detection.

## Tailscale identity authentication

Lookout can authorize an interactive user or node through a local `tailscaled` socket. Enable `auth.tailscale`, allowlist stable user or node IDs, and assign one or more interactive roles: `viewer`, `analyst`, `rule_admin`, or `admin`.

Bearer credentials remain the recommended mechanism for service integrations.