Skip to main content

​
Shell Auth

Programmatic authentication for the Vers platform via SSH key verification and email confirmation.

​
What is Shell Auth?

Shell Auth lets you authenticate with Vers and create API keys from the terminal. It’s designed for CLI tools, AI agents, and automated workflows that need to interact with the Vers API. The only browser interaction is clicking a one-time email verification link.

​
How it works

1. Submit your email + SSH public key
2. Receive a verification email
3. Click the verification link
4. Poll for verification status → receive your org list
5. Create an API key for your selected org

​
Integration flow

# Step 1: Initiate authentication
POST /api/shell-auth
  → Sends verification email
  → Returns nonce for polling

# Step 2: Poll for verification
POST /api/shell-auth/verify-key
  → Returns verified: false (waiting for email click)
  → ... user clicks email link ...
  → Returns verified: true + list of organizations

# Step 3: Create API key
POST /api/shell-auth/api-keys
  → Creates API key for selected organization
  → Returns the API key (shown only once)
New users get an account and organization created automatically on first verification. Existing users just verify their SSH key and select an org.

​
Security

  • Email verification is required before any API key can be created
  • Verification links expire after 10 minutes and are single-use
  • Each SSH key is uniquely bound to one account
  • API keys are never stored in plaintext — only the holder has the key
  • All API communication is over HTTPS

​
Endpoints

EndpointPurpose
POST /api/shell-authInitiate authentication
POST /api/shell-auth/verify-keyCheck verification status + get orgs
POST /api/shell-auth/verify-public-keyLookup verified key (diagnostic)
POST /api/shell-auth/api-keysCreate API key