Skip to main content

​
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"
}
FieldTypeRequiredDescription
emailstringYesUser’s email address
ssh_public_keystringYesVerified SSH public key
labelstringYesLabel for the API key (min 5 characters)
org_namestringNoOrganization 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"
}
FieldDescription
api_keyThe full API key — store it securely, it cannot be retrieved again
api_key_idThe key’s unique identifier
org_idThe organization the key belongs to
org_nameThe organization name

​
Errors

StatusErrorCause
400Invalid requestValidation failed (email, key format, label too short)
400User has no organizationsUser needs to complete signup first
401Invalid or unverified SSH keySSH key not verified or not found
402Billing could not be verifiedTemporary issue — retry later
404Organization not foundSpecified 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