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

{
  "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)

{
  "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

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 until the user clicks the verification link.

Overview

Endpoints

Shell Auth

Initiate

Initiate Authentication

Endpoint

Request

Response

Success (200)

Errors

What happens next

Alias emails

Example

Next step

​Initiate Authentication

​Endpoint

​Request

​Response

​Success (200)

​Errors

​What happens next

​Alias emails

​Example

​Next step

Initiate Authentication

Endpoint

Request

Response

Success (200)

Errors

What happens next

Alias emails

Example

Next step