Skip to main content

​
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"
}
FieldTypeRequiredDescription
emailstringYesUser’s email address
ssh_public_keystringYesSSH public key (any format)
bodystringNoCustom 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..."
}
FieldDescription
user_idThe user’s ID
is_new_userWhether this is a first-time user
nonceServer-generated nonce for tracking this verification

​
Errors

StatusErrorCause
400Invalid email or SSH key formatValidation failed
403Base account does not existAlias email (+ syntax) where the primary account hasn’t signed up
403Base account is not verifiedAlias email where the primary account hasn’t completed verification
409SSH key already registered to another accountThis 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.