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

# Api keys

# 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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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)

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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
```