The [HTTPS API](/docs/https-api) page shows how to authenticate to the exe.dev API. For programmatic access to VMs, we support something very similar.

Our [HTTPS auth proxy](/docs/proxy) gates access to websites on your VMs, but it assumes a browser and cookies. For API servers or `git push` over HTTPS, you can generate bearer tokens that the proxy will respect.

Using `ssh-key generate-api-key --vm`:

```bash
ssh exe.dev ssh-key generate-api-key --vm=my-vm --label=deploy
```

You can also [create VM tokens locally](/docs/https-api-local-key#vm-tokens-via-local-signing) by signing with a different namespace.

## How it works

VM tokens work just like API tokens, with two differences:

1. **Namespace**: The signing namespace is `v0@VMNAME.exe.xyz` (instead of `v0@exe.dev`), scoping the token to a specific VM. When using `ssh-key generate-api-key --vm`, this is handled for you.

2. **Ctx header**: When a request is authenticated via token, the [`ctx`](/docs/https-api#granular-permissions) field from the payload is passed verbatim to your VM's HTTP server in the `X-ExeDev-Token-Ctx` header. The contents are signed, so your server can use them for its own authorization rules.

## Authentication methods

Tokens can be provided in three ways:

- **Bearer token in `X-Exedev-Authorization`** *(preferred)*: Add an
  `X-Exedev-Authorization: Bearer <token>` HTTP header. The proxy
  consumes and strips this header before forwarding to your VM.
- **Bearer token in `Authorization`** *(deprecated)*: Add an
  `Authorization: Bearer <token>` HTTP header. Prefer
  `X-Exedev-Authorization` for new integrations.
- **Basic auth**: Username is ignored; password is the token. This works with tools like `git` that use basic auth for HTTPS. (VM proxy only, not `/exec`.)

## What your server receives

When a request is authenticated via token, your server receives these headers:

- `X-ExeDev-UserID`: Your exe.dev user ID
- `X-ExeDev-Email`: Your email address
- `X-ExeDev-Token-Ctx`: The `ctx` field from the token, passed verbatim (if present)

## Using with git

For git HTTPS access, save the token to a file and configure git to supply it as the password via basic auth.

```bash
echo "$TOKEN" > ~/.ssh/exe_dev_token
```

```bash
git config credential.helper '!f() { echo "password=$(cat ~/.ssh/exe_dev_token)"; }; f'
```

```bash
git clone https://myvm.exe.xyz/repo.git
```