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

# Authentication

> Issue and revoke credentials, scope access and configure transport security.

Vexlo uses bearer tokens to separate record delivery from read access. An ingest token lets
a relay send records and update capture policy. A read token lets the web UI, HTTP clients
and MCP server query execution data.

## Token roles and scope

| Role | Permissions | Team scope |
| - | - | - |
| `ingest` | Send records and heartbeats; update capture policy | Exactly one team |
| `read` | Query requests, values, functions, coverage and health | One or more teams |

The token's team is the data-access boundary. A read query can narrow the token's team set;
it cannot widen it. A trace outside the token's scope returns the same `404` as a missing
trace. An ingest token can also restrict writes to a service and deployment environment.

Token administration opens the server database directly. Run token commands on the server
host or where its storage is accessible. They open `vexlo.db` inside the selected data
directory and do not accept a separate `-db-path` option.

## Issue a read token

Set the server's data-directory path, then create a read token for team `development` and
save its output:

```sh theme={"system"}
export VEXLO_DATA_DIR=/path/to/server/data
umask 077
TOKEN_FILE=$(mktemp "$VEXLO_DATA_DIR/read-token.XXXXXX")
vexlo token create -role read -team development > "$TOKEN_FILE"
export VEXLO_TOKEN=$(sed -n 's/^token:    //p' "$TOKEN_FILE")
VEXLO_READ_TOKEN_ID=$(sed -n 's/^token_id: //p' "$TOKEN_FILE")
```

The token file contains both the credential and its `token_id`. Token creation displays the
secret once. `token list` returns metadata, not the secret, so retain the file or store the
credential before discarding that output.

Set the server's base URL and verify the new token:

```sh theme={"system"}
export VEXLO_ENDPOINT=http://127.0.0.1:8080
curl --silent --show-error "$VEXLO_ENDPOINT/v1/whoami" \
  -H "Authorization: Bearer $VEXLO_TOKEN"
```

Use the read credential in the web UI's **Read token** field. For agent setup, follow
[Connect an agent](https://docs.vexlo.ai/agents/connect.md). A read token does not authorize record ingestion.

## Restrict an ingest credential

An ingest token accepts a single team and optional service and environment restrictions.
Set the server's data-directory path before creating the token:

```sh theme={"system"}
export VEXLO_DATA_DIR=/path/to/server/data
vexlo token create -role ingest -team platform \
  -service checkout-service -environment staging
```

The relay using this token must send `checkout-service` records with the `staging`
environment. A mismatched service or environment is rejected; omitting the environment is
also rejected for an environment-restricted token. The relay treats these responses as terminal
and advances past the affected batch. Use a separate queue and relay for each scoped credential
so it only forwards records within that credential's scope. See
[terminal rejection](https://docs.vexlo.ai/deployment/retention.md#retryable-failures-and-terminal-rejection).
The relay supplies the environment through `-environment` or `VEXLO_ENVIRONMENT`; the SDK
supplies its service name.

For read access across teams, pass a comma-separated list to `-team`, such as
`platform,operations`. Read scope is selected by team; service and environment query filters
narrow the records returned by a request.

## Inspect token metadata

List the token IDs and their metadata from the server's data directory:

```sh theme={"system"}
export VEXLO_DATA_DIR=/path/to/server/data
vexlo token list
```

## Replace an active read credential

Issue a replacement before revoking the active credential. This example rotates the unpinned
`development` credential used above. Before adapting it for another credential, inspect
`token list` and preserve the required team list. Set the server paths and the active token's
value and ID:

```sh theme={"system"}
export VEXLO_DATA_DIR=/path/to/server/data
export VEXLO_ENDPOINT=http://127.0.0.1:8080
export VEXLO_TOKEN=your-active-read-token
VEXLO_READ_TOKEN_ID=token-id-to-replace
OLD_TOKEN=$VEXLO_TOKEN
OLD_TOKEN_ID=$VEXLO_READ_TOKEN_ID
TOKEN_FILE=$(mktemp "$VEXLO_DATA_DIR/read-token.XXXXXX")
vexlo token create -role read -team development > "$TOKEN_FILE"
export VEXLO_TOKEN=$(sed -n 's/^token:    //p' "$TOKEN_FILE")
VEXLO_READ_TOKEN_ID=$(sed -n 's/^token_id: //p' "$TOKEN_FILE")
curl --silent --show-error "$VEXLO_ENDPOINT/v1/whoami" \
  -H "Authorization: Bearer $VEXLO_TOKEN"
```

Update the credential source used by each reader, including saved environment files, the UI
and MCP configuration, before revoking the old ID. Then verify both sides of the replacement:

```sh theme={"system"}
vexlo token revoke "$OLD_TOKEN_ID"
curl --silent --show-error "$VEXLO_ENDPOINT/v1/whoami" \
  -H "Authorization: Bearer $OLD_TOKEN"
curl --silent --show-error "$VEXLO_ENDPOINT/v1/whoami" \
  -H "Authorization: Bearer $VEXLO_TOKEN"
```

The old credential must be rejected, while the replacement still returns its identity.
For relay ingest-token replacement, configure the new credential in the relay and verify a
new execution before revoking the old token. The relay supports
[token-file reload](https://docs.vexlo.ai/deployment/configuration.md#reload-the-relay-destination-or-token).

## Revoke a credential

Choose the token ID from `vexlo token list`, then revoke that ID:

```sh theme={"system"}
export VEXLO_DATA_DIR=/path/to/server/data
vexlo token revoke 'token-id-to-revoke'
```

A request using the revoked credential returned:

```json theme={"system"}
{"error":{"code":"unauthenticated","message":"token revoked"}}
```

## Transport security

Loopback addresses can use HTTP. A server listening on a non-loopback address requires a TLS
certificate and key through `-tls-cert` / `VEXLO_TLS_CERT_FILE` and
`-tls-key` / `VEXLO_TLS_KEY_FILE`. The server validates the pair during configuration checks.

For example, this check requests a non-loopback address without configuring TLS:

```sh theme={"system"}
vexlo check -api-addr 0.0.0.0:8080
```

The check fails with:

```text theme={"system"}
vexlo: check: vexlo serve: refusing to bind 0.0.0.0:8080: not loopback and no TLS certificate configured; set -tls-cert/-tls-key (or VEXLO_TLS_CERT_FILE/VEXLO_TLS_KEY_FILE), bind to loopback (127.0.0.1, ::1, localhost) for local dev, or set -allow-insecure-http/VEXLO_ALLOW_INSECURE_HTTP
```

The relay also refuses non-loopback HTTP destinations unless explicitly allowed. Use an
`https://` destination when forwarding to a TLS listener. `-allow-insecure-http` or
`VEXLO_ALLOW_INSECURE_HTTP` bypasses the corresponding transport check; it does not disable
bearer authentication.

## Local access without authentication

`-no-auth` or `VEXLO_NO_AUTH` disables credential checks and forces the server listener to
`127.0.0.1`, preserving the configured port. Its rows and queries use the team from `-team` /
`VEXLO_TEAM`, defaulting to `default`. This mode cannot be combined with header trust.

For a proxy-authenticated deployment, `-header-trust` enables read access through
`X-Vexlo-Team` and `X-Vexlo-Trust-Secret` when `Authorization` is absent. It requires
`-header-trust-secret` / `VEXLO_HEADER_TRUST_SECRET`. Ingest requests still use ingest tokens.
See [Configuration](https://docs.vexlo.ai/deployment/configuration.md) for the exact settings.


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