> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

# 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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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

| Endpoint                                                                | Purpose                              |
| ----------------------------------------------------------------------- | ------------------------------------ |
| [POST /api/shell-auth](/shell-auth/initiate)                            | Initiate authentication              |
| [POST /api/shell-auth/verify-key](/shell-auth/verify-key)               | Check verification status + get orgs |
| [POST /api/shell-auth/verify-public-key](/shell-auth/verify-public-key) | Lookup verified key (diagnostic)     |
| [POST /api/shell-auth/api-keys](/shell-auth/api-keys)                   | Create API key                       |