Skip to main content
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

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:
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:
Use the read credential in the web UI’s Read token field. For agent setup, follow Connect an agent. 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:
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. 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:

​
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:
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:
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.

​
Revoke a credential

Choose the token ID from vexlo token list, then revoke that ID:
A request using the revoked credential returned:

​
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:
The check fails with:
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 for the exact settings.