> ## 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.

# Initiate

# Initiate Authentication

Start the Shell Auth flow by submitting an email and SSH public key. Sends a verification email to confirm ownership.

## Endpoint

```
POST /api/shell-auth
```

## Request

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "email": "user@example.com",
  "ssh_public_key": "ssh-ed25519 AAAA...",
  "body": "optional message included in verification email"
}
```

| Field            | Type   | Required | Description                                       |
| ---------------- | ------ | -------- | ------------------------------------------------- |
| `email`          | string | Yes      | User's email address                              |
| `ssh_public_key` | string | Yes      | SSH public key (any format)                       |
| `body`           | string | No       | Custom message appended to the verification email |

## Response

### Success (200)

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "success": true,
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "is_new_user": true,
  "nonce": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "ssh_public_key": "ssh-ed25519 AAAA..."
}
```

| Field         | Description                                           |
| ------------- | ----------------------------------------------------- |
| `user_id`     | The user's ID                                         |
| `is_new_user` | Whether this is a first-time user                     |
| `nonce`       | Server-generated nonce for tracking this verification |

### Errors

| Status | Error                                         | Cause                                                               |
| ------ | --------------------------------------------- | ------------------------------------------------------------------- |
| 400    | Invalid email or SSH key format               | Validation failed                                                   |
| 403    | Base account does not exist                   | Alias email (`+` syntax) where the primary account hasn't signed up |
| 403    | Base account is not verified                  | Alias email where the primary account hasn't completed verification |
| 409    | SSH key already registered to another account | This SSH key is bound to a different email                          |

## What happens next

After calling this endpoint:

* **New users**: An account is created. On email verification, an organization and free subscription are provisioned automatically.
* **Existing users**: The SSH key is registered. On email verification, it's activated for authentication.

## Alias emails

You can use `+` syntax (e.g., `alice+agent@company.com`) to create agent accounts that share the primary user's organizations. The primary account (`alice@company.com`) must exist and be verified first.

## Example

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST https://vers.sh/api/shell-auth \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@company.com",
    "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample...",
    "body": "Login from dev-machine-01"
  }'
```

## Next step

Poll [POST /api/shell-auth/verify-key](/shell-auth/verify-key) until the user clicks the verification link.