Eve Auth and Secrets

Use this workflow to log in to Eve and manage secrets for your app.

When to Use

• Setting up a new project profile
• Authentication failures
• Adding or rotating secrets
• Secret interpolation errors during deploys
• Setting up identity providers or org invites

Authentication

eve auth login
eve auth login --ttl 30                # custom token TTL (1-90 days)
eve auth status

Challenge-Response Flow

Eve uses challenge-response authentication. The default provider is github_ssh:

1. Client sends SSH public key fingerprint
2. Server returns a challenge (random bytes)
3. Client signs the challenge with the private key
4. Server verifies the signature and issues a JWT

Token Types

JWT payloads include sub (user ID), org_id, scope, and exp. Verify tokens via the JWKS endpoint: GET /auth/jwks.

Permissions

Check what the current token can do:

eve auth permissions

Register additional identities for multi-provider access:

curl -X POST "$EVE_API_URL/auth/identities" -H "Authorization: Bearer $TOKEN" \
  -d '{"provider": "nostr", "external_id": "<pubkey>"}'

Identity Providers

Eve supports pluggable identity providers. The auth guard tries Bearer JWT first, then provider-specific request auth.

Nostr Authentication

Two paths:

• Challenge-response: Like SSH but signs with Nostr key. Use eve auth login --provider nostr.
• NIP-98 request auth: Every API request signed with a Kind 27235 event. Stateless, no stored token.

Org Invites

Invite external users by identity hint:

# Admin creates invite targeting a Nostr pubkey
curl -X POST "$EVE_API_URL/auth/invites" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"org_id": "org_xxx", "role": "member", "provider_hint": "nostr", "identity_hint": "<pubkey>"}'

When the pubkey authenticates, Eve auto-provisions their account and org membership.

Token Minting (Admin)

Mint tokens for bot/service users without SSH login:

# Mint token for a bot user (creates user + membership if needed)
eve auth mint --email app-bot@example.com --org org_xxx

# With custom TTL (1-90 days, default: server configured)
eve auth mint --email app-bot@example.com --org org_xxx --ttl 90

# Scope to project with admin role
eve auth mint --email app-bot@example.com --project proj_xxx --role admin

Print the current access token (useful for scripts):

eve auth token

Key Rotation

Rotate the JWT signing key:

1. Set EVE_AUTH_JWT_SECRET_NEW alongside the existing secret
2. Server starts signing with the new key but accepts both during the grace period
3. After grace period (EVE_AUTH_KEY_ROTATION_GRACE_HOURS), remove the old secret
4. Emergency rotation: set only the new key (immediately invalidates all existing tokens)

Project Secrets

# Set a secret
eve secrets set API_KEY "your-api-key" --project proj_xxx

# List keys (no values)
eve secrets list --project proj_xxx

# Delete a secret
eve secrets delete API_KEY --project proj_xxx

# Import from file
eve secrets import .env --project proj_xxx

Secret Interpolation

Reference secrets in .eve/manifest.yaml using ${secret.KEY}:

services:
  api:
    environment:
      API_KEY: ${secret.API_KEY}

Manifest Validation

Validate that all required secrets are set before deploying:

eve manifest validate --validate-secrets    # check secret references
eve manifest validate --strict              # fail on missing secrets

Local Secrets File

For local development, create .eve/dev-secrets.yaml (gitignored):

secrets:
  default:
    API_KEY: local-dev-key
    DB_PASSWORD: local-password
  staging:
    DB_PASSWORD: staging-password

Worker Injection

At job execution time, resolved secrets are injected as environment variables into the worker container. File-type secrets are written to disk and referenced via EVE_SECRETS_FILE. The file is removed after the agent process reads it.

Git Auth

The worker uses secrets for repository access:

• HTTPS: github_token secret → Authorization: Bearer header
• SSH: ssh_key secret → written to ~/.ssh/ and used via GIT_SSH_COMMAND

Troubleshooting

Incident Response (Secret Leak)

If a secret may be compromised:

1. Contain: Rotate the secret immediately via eve secrets set
2. Invalidate: Redeploy affected environments
3. Audit: Check eve job list for recent jobs that used the secret
4. Recover: Generate new credentials at the source (GitHub, AWS, etc.)
5. Document: Record the incident and update rotation procedures