Exe.dev's API to create a new machine is:

ssh exe.dev new --name=restless --json

That assumes your SSH key is already registered to your account.

If you want to do it over HTTPS, it's:

curl -X POST https://exe.dev/exec \
  -H "Authorization: Bearer $TOKEN" \
  -d 'new --name=restless --json'

Our CLI and our API are one and the same. The conventions are unix-y (how to parse command-line flags) rather than web-by, but they're familiar to our end users, and you don't have to learn two different conventions.

Minting Your Own Tokens

The only tricky bit is giving our users bearer tokens, and here we did something new: you can use your SSH key to mint your own tokens, and you can give those self-minted tokens restrictions (when they're valid, what they can do) without chatting with us. If the signature checks out, we know that the token was generated by the SSH private key.

We walk through building a token step by step in our documentation, but this shell function does the trick:

exetoken() {
  # Generate an exe.dev API token.
  #   exetoken [permissions_json] [ssh_key_path]
  #   permissions_json defaults to '{}' (no restrictions)
  #   ssh_key_path defaults to the first IdentityFile from ssh config
  local perms
  if [ -n "$1" ]; then
    perms="$1"
  else
    perms='{}'
  fi
  local key
  if [ -n "$2" ]; then
    key="$2"
  else
    local default_key=$(ssh -G exe.dev | grep -i identityfile | head -n1 | awk '{print $2}')
    key="${default_key/#\~/$HOME}"
  fi
  b() { tr -d '\n=' | tr '+/' '-_'; }
  local p=$(printf '%s' "$perms" | base64 | b)
  local s=$(printf '%s' "$perms" | ssh-keygen -Y sign -f "$key" -n v0@exe.dev 2>/dev/null | sed '1d;$d' | b)
  echo "exe0.$p.$s"
}

The key aspects here are the inputs:

The output is the permissions and the signature of the permissions, encoded with URL-safe base64 to prevent any troubles.

$ curl -s -X POST https://exe.dev/exec \
    -H "Authorization: Bearer $(exetoken '{"cmds":["whoami"]}')" \
    -d whoami | jq -r '.email'
philip.zeyliger@bloggy.exe.xyz

Gadzooks, it works!

Scopes, Expiry, and Revocation

You can associate multiple SSH keys with an exe.dev account. Removing an SSH key from your exe.dev account revokes all tokens signed with that SSH key.

This, dare we say unusual, scheme gives you scopes, expiry, offline token creation, and revocation. We admit it's a little weird.

Extending to the SSH Auth Proxy

Exe.dev VMs come with a built-in auth proxy. If you wanted to script talking to a web server on your VM, you could log in manually and steal the cookie. Stealing cookies is naughty, so you could instead mark the VM publicly accessible and implement your own authentication. Our API keys give you a third way: mint a bearer token scoped to just that VM, and access it directly.

For VM tokens, the signing namespace changes from v0@exe.dev to v0@myvm.exe.xyz:

# Without a token — the proxy redirects you to log in:
$ curl -s -o /dev/null -w "%{http_code}" https://myvm.exe.xyz/api/data
307

# With a bearer token — you're in:
$ curl -s -H "Authorization: Bearer $VM_TOKEN" https://myvm.exe.xyz/api/data
{"status": "ok"}

References

See https://exe.dev/docs/https-api for the full details, including how to mint short-lived tokens.