AuthenticationSingle-user alpha

Auth & Organizations

Name: LyDos Agent OS
Author: LYDOS

LYDOS uses API-key authentication with file-based local storage. Keys are never sent to third parties, masked in all CLI output, and overridable via environment variables for CI pipelines.

API key format

All keys start with lyd_sk_. Created at registration, shown once.

Secure storage

Keys stored in ~/.config/lydos/auth.json with 0600 file permissions.

Stateless auth

Every API request is authenticated independently. No server-side sessions.

Org support

Organization features are in active development — see roadmap.

API Key Format

LYDOS API keys follow a fixed prefix format that makes them easy to identify in source code, logs, and secret scanners. The prefix is lyd_sk_ followed by a cryptographically random 32-character base62 string.

key formatTEXT

# Format
lyd_sk_<32 base62 characters>

# Example (never use this key — it is illustrative only)
lyd_sk_a8Kx3mN2pQ7rT4wZ1bY6cF9dG0hJ5vL

Property	Value
Prefix	lyd_sk_
Total length	39 characters
Entropy	~190 bits (32 base62 chars)
Shown once	Yes — displayed only at registration, never again
Revocation	Via lydos auth logout (local) or dashboard (future)
Expiry	No expiry — rotate manually when compromised

Token Storage

The LYDOS CLI stores your API key in a local JSON file on your filesystem. The file is created with mode 0600 (readable only by the current user) at first login and updated on each lydos auth login call.

terminalBASH

# Auth file location
~/.config/lydos/auth.json

# File is created with 0600 permissions automatically
# Verify permissions after first login
ls -la ~/.config/lydos/auth.json
# → -rw------- 1 user group 87 Jan 01 12:00 auth.json

~/.config/lydos/auth.jsonJSON

{
  "api_key": "lyd_sk_a8Kx3mN2pQ7rT4wZ1bY6cF9dG0hJ5vL",
  "api_url": "http://localhost:8888",
  "created_at": "2026-03-28T10:00:00Z"
}

WARNING

Never commit ~/.config/lydos/auth.json to version control. Add it to your global ~/.gitignore_global as a precaution. The key gives full access to all LYDOS API endpoints.

CLI output masking

The CLI masks your API key in all output and log files. The key is shown as lyd_sk_a8Kx••••••••••••••••wxyz — the first 10 characters and last 4 characters visible, all middle characters replaced with bullets. This applies in lydos whoami, lydos auth token, and all server log output.

terminalBASH

$ lydos auth token
API key (masked): lyd_sk_a8Kx••••••••••••••••J5vL

# To copy the full key to clipboard (macOS)
$ lydos auth token --raw | pbcopy

# To copy the full key to clipboard (Linux with xclip)
$ lydos auth token --raw | xclip -selection clipboard

Environment Variable Override

In CI/CD pipelines and containerized environments, you will not run lydos auth login interactively. Set the LYDOS_API_KEY environment variable instead — it takes precedence over the stored file.

terminalBASH

# Set key via environment variable (takes precedence over auth.json)
export LYDOS_API_KEY="lyd_sk_your_key_here"

# Verify it is being used
lydos whoami
# → API URL:  http://localhost:8888
# → Auth:     env:LYDOS_API_KEY (lyd_sk_a8Kx••••J5vL)

# In GitHub Actions
- name: Run LYDOS agent
  env:
    LYDOS_API_KEY: ${{ secrets.LYDOS_API_KEY }}
  run: lydos agent run code-reviewer --prompt "Review PR changes"

Environment variable	Purpose	Precedence
`LYDOS_API_KEY`	API key — overrides ~/.config/lydos/auth.json	1 (highest)
`LYDOS_API_URL`	Server URL — overrides config file api_url	1 (highest)
`LYDOS_TIMEOUT`	Request timeout in seconds (default: 30)	1 (highest)
`LYDOS_DRY_RUN`	Set to false to disable dry-run mode in CI	1 (highest)

Session Behavior

LYDOS uses a stateless authentication model. There are no server-side sessions, no session tokens, and no refresh tokens. Every API request must carry a valid API key in the Authorization header. The server validates the key on each request independently.

terminalBASH

# Direct API calls always require the Authorization header
curl -s http://localhost:8888/api/agents \
  -H "Authorization: Bearer lyd_sk_your_key_here" \
  | python3 -m json.tool

# The CLI handles this automatically — it reads from auth.json or LYDOS_API_KEY
lydos agent list

# For programmatic use with the Python SDK
from lydos import LydosClient
client = LydosClient(
    base_url="http://localhost:8888",
    api_key="lyd_sk_your_key_here"   # or reads LYDOS_API_KEY automatically
)
agents = client.agents.list()

Workspace Model

Each project using LYDOS has a .lydos/ directory at its root. This directory contains project-specific configuration, agent run history, and the safety policy. It is separate from the global auth file.

project layoutTEXT

my-project/
├── .lydos/
│   ├── config.yaml          # Project-specific safety config and agent defaults
│   ├── history/             # Agent run logs (JSON, one file per task)
│   └── cache/               # Semantic analysis cache (gitignore-able)
├── .env                     # API keys — never commit
├── src/
└── ...

# Global config (applies to all projects unless overridden)
~/.config/lydos/
├── auth.json                # API key storage (0600)
├── config.yaml              # Global defaults
└── logs/
    └── server.log           # Aggregated CLI operation log

TIP

Add .lydos/cache/ to your .gitignore. The .lydos/config.yaml and .lydos/history/ can be committed — they contain no secrets.

Organization Support

LYDOS currently operates in single-user mode. Organization features — team API keys, role-based access control (RBAC), audit log sharing, and per-team resource quotas — are implemented in Q63 Multi-User engine and are being stabilized for the first team release.

Q63 Multi-User — Organization feature status

implemented

JWT-based multi-user sessions— Active in Q63 — requires LYDOS_JWT_SECRET

implemented

User registration API— POST /api/q63/users/register

implemented

RBAC (roles: admin, operator, reader)— Role enforcement via Q65 Governance

in-progress

Team API keys— Scheduled for next alpha milestone

planned

Organization dashboard— UI layer being designed

planned

SSO / SAML / OIDC— Enterprise tier only

CLI Auth Commands

lydos auth login

Authenticate the CLI with your API key. On first run this prompts for your key and writes it to ~/.config/lydos/auth.json with 0600 permissions.

terminalBASH

$ lydos auth login
Enter your LYDOS API key (lyd_sk_...):
  Validating key against http://localhost:8888...
  OK — authenticated as: operator
  Key saved to ~/.config/lydos/auth.json (0600)

# Non-interactive (pipe key in)
echo "lyd_sk_your_key" | lydos auth login --stdin

lydos auth logout

Remove the stored API key from the local auth file. This does not invalidate the key on the server — it only removes it from your local machine.

terminalBASH

$ lydos auth logout
  Removing key from ~/.config/lydos/auth.json...
  Cleared.

lydos whoami

Show the current authentication state — which key is active (masked), the server URL, and the auth source (file or environment variable).

terminalBASH

$ lydos whoami
API URL:    http://localhost:8888
Auth:       file (~/.config/lydos/auth.json)
Key:        lyd_sk_a8Kx••••••••••••••••J5vL
Timeout:    30s
Dry-run:    true

# JSON output for scripting
$ lydos whoami --json
{
  "api_url": "http://localhost:8888",
  "auth_source": "file",
  "key_masked": "lyd_sk_a8Kx••••••••••••••••J5vL",
  "timeout": 30,
  "dry_run": true
}

lydos auth token

Display the current active key — masked by default, or in full with --raw.

terminalBASH

$ lydos auth token
lyd_sk_a8Kx••••••••••••••••J5vL

# Show full key (pipe to clipboard — never print to terminal in shared sessions)
$ lydos auth token --raw | pbcopy

Auth & Organizations

API Key Format

Token Storage

CLI output masking

Environment Variable Override

Session Behavior

Workspace Model

Organization Support

CLI Auth Commands

lydos auth login

lydos auth logout

lydos whoami

lydos auth token

Related Documentation