Skip to content

Authentication

Alpha Access Required

Lucid is in private alpha. Request access to get your credentials.

This guide covers authentication methods supported by the Lucid CLI, including email/password login and API keys for automation.

Authentication Methods

Method Best For Persistence
Email/Password Interactive CLI use Session-based (JWT)
API Key CI/CD, automation, scripts Long-lived

Email/Password Login

The most common authentication method for interactive CLI usage.

Interactive Login

lucid loginAuthenticate with API key? [y/N]: n
Email: [email protected]
Password:
Logged in as [email protected]

Login with Email Flag

Provide the email via command line and password via environment variable or prompt:

lucid login -e [email protected]Authenticate with API key? [y/N]: n
Password:
Logged in as [email protected]

Or use the LUCID_PASSWORD environment variable for non-interactive use:

LUCID_PASSWORD=mypassword lucid login -e [email protected]

Get Access

Lucid is in private alpha. Request access or contact your administrator.

API Keys

API keys provide persistent authentication for automation, CI/CD pipelines, and programmatic access.

Generate an API Key

Generate a new API key during login with the --generate-key flag:

lucid login --generate-keyAuthenticate with API key? [y/N]: n
Email: [email protected]
Password:
Logged in as [email protected]
Generated persistent API key (stored in config)

Or with email provided:

LUCID_PASSWORD=mypassword lucid login -e [email protected] --generate-key

The generated API key is automatically stored in your config file for future use.

Authenticate with API Key

Use the API key via environment variable (recommended for CI/CD):

export LUCID_API_KEY=luc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxlucid statusAgents (2):
NAME STATUS MODEL GPU
my-agent running meta-llama/Llama-3.3-70B H100
prod-agent running meta-llama/Llama-3.1-8B A100

Or authenticate interactively by entering an API key at the prompt:

lucid loginAuthenticate with API key? [y/N]: y
API Key:
Authenticated as [email protected]

Environment Variables

The Lucid CLI supports several environment variables for configuration.

Authentication Variables

Variable Description Example
LUCID_API_KEY API key for authentication luc_xxxxxxxxxxxxxxxxxxxx
LUCID_PASSWORD Password for login (avoids interactive prompt) mypassword

Configuration Variables

Variable Description Default
LUCID_CONFIG_PATH Path to config file ~/.lucid/config.yaml

Custom API URL

Use the --api-url flag to connect to a different Lucid deployment:

lucid login --api-url http://localhost:8000

Example: CI/CD Pipeline

# GitHub Actions example
name: Deploy to Lucid

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Lucid CLI
        run: pip install lucid-cli

      - name: Deploy environment
        env:
          LUCID_API_KEY: ${{ secrets.LUCID_API_KEY }}
        run: |
          lucid apply -f environment.yaml
          lucid status

Example: Docker

FROM python:3.12-slim

RUN pip install lucid-cli

# Set at runtime, not build time
ENV LUCID_API_KEY=""

ENTRYPOINT ["lucid"]

docker run -e LUCID_API_KEY=luc_xxx my-lucid-image status

Credential Storage

Credentials are stored locally in ~/.lucid/config.yaml:

api_url: https://verifier.lucid.sh
api_key: luc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or for JWT auth:
# auth_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
# token_expires_at: 2024-01-16T10:30:00Z

Security Notes

  • The config file should be readable only by the current user (chmod 600)
  • JWT tokens expire; use --generate-key to create a persistent API key
  • Never commit credentials to version control
  • Use LUCID_PASSWORD environment variable instead of passing passwords on the command line to avoid shell history exposure

Clear Credentials

To clear stored credentials, delete or edit the config file:

rm ~/.lucid/config.yaml

Or edit the file to remove specific credentials.

Troubleshooting

"Invalid credentials" Error

lucid login -e [email protected]Password:
Login failed: Invalid credentials

Solution: Verify your email and password. Reset your password at observer.lucid.sh if needed.

"Token expired" Error

lucid statusError: Token expired. Please run 'lucid login' to reauthenticate.

Solution: Run lucid login to refresh your credentials. Consider using --generate-key to create a persistent API key.

"API key invalid" Error

LUCID_API_KEY=luc_invalid lucid statusError: Invalid API key. The key may have been revoked.

Solution: Generate a new API key with lucid login --generate-key.

HTTP Warning

If you see a warning about unencrypted HTTP:

[!] WARNING: API URL uses unencrypted HTTP. Credentials may be transmitted in plain text.

This warning appears when using --api-url with a non-HTTPS URL (except localhost). Use HTTPS in production environments.

Agent Authentication

In addition to human authentication, Lucid agents authenticate with external services using three models, configured per-agent through the Observer UI or Access Manifest.

Model Name When Used How It Works
1 Autonomous Identity Agent acts as itself (cron jobs, A2A, MCP) SPIFFE workload identity + OAuth client_credentials grant
2 OBO Delegation Agent acts on behalf of a human RFC 8693 token exchange -- composite token with sub (human) + act (agent)
3 Provisioned Credentials Human stores a secret for agent use Sidecar injects credentials at runtime -- agent never sees raw secrets

Agent auth is configured through the Identity page (Model 1), Integrations page (Model 3), and Delegation/Consent flows (Model 2) in the Observer UI. See the VAP guide for full architecture details.

Next Steps