Create API Key

Create an API key for an authenticated user. Requires a verified SSH key pair and an active organization.

Endpoint

POST /api/shell-auth/api-keys

Request

{
  "email": "user@example.com",
  "ssh_public_key": "ssh-ed25519 AAAA...",
  "label": "my-api-key",
  "org_name": "acme-corp"
}

Field	Type	Required	Description
`email`	string	Yes	User’s email address
`ssh_public_key`	string	Yes	Verified SSH public key
`label`	string	Yes	Label for the API key (min 5 characters)
`org_name`	string	No	Organization to create the key for. Defaults to user’s first org.

Response

Success (200)

{
  "success": true,
  "api_key": "076a62f7-90ac-4358-8e71-7a4e96f6f3e97a44528945ffcfe2d65f2f33e18e07bc070f8dde30f19f373a936275f20111b0",
  "api_key_id": "076a62f7-90ac-4358-8e71-7a4e96f6f3e9",
  "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "org_name": "acme-corp"
}

Field	Description
`api_key`	The full API key — store it securely, it cannot be retrieved again
`api_key_id`	The key’s unique identifier
`org_id`	The organization the key belongs to
`org_name`	The organization name

Errors

Status	Error	Cause
400	Invalid request	Validation failed (email, key format, label too short)
400	User has no organizations	User needs to complete signup first
401	Invalid or unverified SSH key	SSH key not verified or not found
402	Billing could not be verified	Temporary issue — retry later
404	Organization not found	Specified `org_name` doesn’t exist or user doesn’t have access

Permissions

API keys created via Shell Auth are granted:

View Clusters — read access to VMs
Create Clusters — create and manage VMs

Keys are also visible in the Vers web dashboard under your organization’s API Keys settings.

Examples

Create key for default org

curl -X POST https://vers.sh/api/shell-auth/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@company.com",
    "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample...",
    "label": "dev-machine-key"
  }'

Create key for a specific org

curl -X POST https://vers.sh/api/shell-auth/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@company.com",
    "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample...",
    "label": "acme-project-key",
    "org_name": "acme-corp"
  }'

Complete integration example

# 1. Initiate auth
curl -s -X POST https://vers.sh/api/shell-auth \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@company.com","ssh_public_key":"ssh-ed25519 AAAA..."}'

echo "Verification email sent. Check your inbox."

# 2. Poll for verification
while true; do
  VERIFY=$(curl -s -X POST https://vers.sh/api/shell-auth/verify-key \
    -H "Content-Type: application/json" \
    -d '{"email":"alice@company.com","ssh_public_key":"ssh-ed25519 AAAA..."}')

  VERIFIED=$(echo $VERIFY | jq -r '.verified')
  if [ "$VERIFIED" = "true" ]; then
    echo "Verified!"
    echo $VERIFY | jq '.orgs'  # Show available orgs
    break
  fi
  sleep 3
done

# 3. Create API key for selected org
API_KEY=$(curl -s -X POST https://vers.sh/api/shell-auth/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "email":"alice@company.com",
    "ssh_public_key":"ssh-ed25519 AAAA...",
    "label":"my-key",
    "org_name":"acme-corp"
  }' | jq -r '.api_key')

echo "API key: $API_KEY"
# Store this key securely — it won't be shown again

Overview

Endpoints

Shell Auth

Api keys

Create API Key

Endpoint

Request

Response

Success (200)

Errors

Permissions

Examples

Create key for default org

Create key for a specific org

Complete integration example

​Create API Key

​Endpoint

​Request

​Response

​Success (200)

​Errors

​Permissions

​Examples

​Create key for default org

​Create key for a specific org

​Complete integration example

Create API Key

Endpoint

Request

Response

Success (200)

Errors

Permissions

Examples

Create key for default org

Create key for a specific org

Complete integration example