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
• Adding SSO login to an Eve-deployed app
• Setting up access groups and scoped data-plane authorization
• Configuring group-aware RLS for environment databases

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

Type	Issued Via	Use Case
User Token	eve auth login	Interactive CLI sessions
Job Token	Worker auto-issued	Agent execution within jobs
Minted Token	eve auth mint	Bot/service accounts

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

Role and org membership changes take effect immediately -- the server resolves permissions from live DB memberships, not stale JWT claims. When a request includes a project_id but no org_id, the permission guard derives the org context from the project's owning org.

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.

Provider	Auth Method	Use Case
github_ssh	SSH challenge-response	Default CLI login
nostr	NIP-98 request auth + challenge-response	Nostr-native users

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 via the CLI or API:

# Invite with SSH key registration (registers key so the user can log in immediately)
eve admin invite --email [email protected] --ssh-key ~/.ssh/id_ed25519.pub --org org_xxx

# Invite with GitHub identity
eve admin invite --email [email protected] --github ghuser --org org_xxx

# Invite with web-based auth (Supabase)
eve admin invite --email [email protected] --web --org org_xxx

# API: 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>"}'

If no auth method is specified (--github, --ssh-key, or --web), the CLI warns that the user will not be able to log in. The user can self-register later via eve auth request-access --org "Org Name" --ssh-key ~/.ssh/id_ed25519.pub --wait.

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

For app-driven onboarding, use the org-scoped invite API instead of the legacy admin invite flow:

# Create an org-scoped Supabase invite with a return URL for the app
curl -X POST "$EVE_API_URL/orgs/org_xxx/invites" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "member",
    "redirect_to": "https://app.example.com/invite/complete",
    "app_context": { "project_id": "proj_123" }
  }'

# Search existing org members for an assignee picker
curl "$EVE_API_URL/orgs/org_xxx/members/search?q=ali" \
  -H "Authorization: Bearer $USER_TOKEN"

Use a user token with orgs:invite to create or list these invites and orgs:members:read for member lookup. Invite emails should land on GoTrue's /verify path, not the OAuth callback directly. If the invite is auto-applied during the SSO exchange, Eve returns invite_redirect_to so the SSO callback can land the user back in the target app even when the email provider strips nested redirect params. Current invite onboarding establishes the SSO session first, then sends the user through /set-password before redirecting to the app.

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 [email protected] --org org_xxx

# With custom TTL (1-90 days, default: server configured)
eve auth mint --email [email protected] --org org_xxx --ttl 90

# Scope to project with admin role
eve auth mint --email [email protected] --project proj_xxx --role admin

Print the current access token (useful for scripts):

eve auth token

Self-Service Access Requests

Users without an invite can request access:

eve auth request-access --org "My Company" --email [email protected]
eve auth request-access --org "My Company" --ssh-key ~/.ssh/id_ed25519.pub
eve auth request-access --status <request_id>

Admins approve or reject via:

eve admin access-requests list
eve admin access-requests approve <request_id>
eve admin access-requests reject <request_id> --reason "..."

List responses use the canonical { "data": [...] } envelope.

Approval is atomic (single DB transaction) and idempotent -- re-approving a completed request returns the existing record. If the fingerprint is already registered, Eve reuses that identity owner. If a legacy partial org matches the requested slug and name, Eve reuses it during approval. Failed attempts never leave partial state.

Credential Check

Verify local AI tool credentials:

eve auth creds                # Show Claude + Codex cred status
eve auth creds --claude       # Only Claude
eve auth creds --codex        # Only Codex

Output includes token type (setup-token or oauth), preview, and expiry. Use this to confirm token health before syncing.

OAuth Token Sync

Sync local Claude/Codex OAuth tokens into Eve secrets so agents can use them. Scope precedence: project > org > user.

eve auth sync                       # Sync to user-level (default)
eve auth sync --org org_xxx         # Sync to org-level (shared across org projects)
eve auth sync --project proj_xxx    # Sync to project-level (scoped to one project)
eve auth sync --dry-run             # Preview without syncing

This sets CLAUDE_CODE_OAUTH_TOKEN / CLAUDE_OAUTH_REFRESH_TOKEN (Claude) and CODEX_AUTH_JSON_B64 (Codex/Code) at the requested scope.

Claude Token Types

Token Prefix	Type	Lifetime	Recommendation
sk-ant-oat01-*	setup-token (long-lived)	Long-lived	Preferred for jobs and automation
Other sk-ant-*	oauth (short-lived)	~15 hours	Use for interactive dev; regenerate with claude setup-token

eve auth sync warns when syncing a short-lived OAuth token. Run eve auth creds to inspect token type before syncing.

Automatic Codex/Code Token Write-Back

After each harness invocation, the worker checks if the Codex/Code CLI refreshed auth.json during the session. If the token changed, it is automatically written back to the originating secret scope (user/org/project) so the next job starts with a fresh token. This is transparent and non-fatal -- a write-back failure logs a warning but does not affect the job result.

For Codex/Code credentials, the sync picks the freshest token across ~/.codex/auth.json and ~/.code/auth.json by comparing tokens.expires_at.

Access Groups + Scoped Access

Groups are first-class authorization primitives that segment data-plane access (org filesystem, org docs, environment databases). Create groups, add members, and bind roles with scoped constraints:

# Create a group
eve access groups create --org org_xxx --slug eng-team --name "Engineering"

# Add members
eve access groups members add eng-team --org org_xxx --user user_abc
eve access groups members add eng-team --org org_xxx --service-principal sp_xxx

# Bind a role with scoped access
eve access bind --org org_xxx --group grp_xxx --role data-reader \
  --scope-json '{"orgfs":{"allow_prefixes":["/shared/"]},"envdb":{"schemas":["public"]}}'

# Check effective access
eve access memberships --org org_xxx --user user_abc

Scope Types

Resource	Scope Fields	Example
Org Filesystem	orgfs.allow_prefixes, orgfs.read_only_prefixes	"/shared/", "/reports/"
Org Documents	orgdocs.allow_prefixes, orgdocs.read_only_prefixes	"/pm/features/"
Environment DB	envdb.schemas, envdb.tables	"public", "analytics_*"

Group-Aware RLS

Scaffold RLS helper functions for group-based row-level security in environment databases:

eve db rls init --with-groups

This creates SQL helpers (app.current_user_id(), app.current_group_ids(), app.has_group()) that read session context set by Eve's runtime. Use them in RLS policies:

CREATE POLICY notes_group_read ON notes FOR SELECT
  USING (group_id = ANY(app.current_group_ids()));

Membership Introspection

Inspect a principal's full effective access -- base org/project roles, group memberships, resolved bindings, and merged scopes:

eve access memberships --org org_xxx --user user_abc
eve access memberships --org org_xxx --service-principal sp_xxx

The response includes effective_scopes (merged across all bindings), effective_permissions, and each binding's matched_via (direct or group).

Resource-Specific Access Checks

Check and explain access against a specific data-plane resource:

eve access can orgfs:read /shared/reports --org org_xxx
eve access explain orgfs:write /shared/reports --org org_xxx --user user_abc

The response includes scope_required, scope_matched, and per-grant scope_reason explaining why a binding did or did not match the requested resource path.

Policy-as-Code (v2)

Declare groups, roles, and scoped bindings in .eve/access.yaml. Use version: 2:

version: 2
access:
  groups:
    eng-team:
      name: Engineering Team
      description: Scoped access for engineering collaborators
      members:
        - type: user
          id: user_abc
  roles:
    app_editor:
      scope: org
      permissions:
        - orgdocs:read
        - orgdocs:write
        - orgfs:read
        - envdb:re