# HTTPS Tokens for VMs


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`.)

## Requests without valid credentials

A private VM sends browsers to the exe.dev login page. Everything else gets
`401 Unauthorized` instead: WebSocket upgrades, and requests whose `Accept`
header doesn't explicitly name `text/html` (such as curl's `*/*`, a missing
`Accept`, or `application/json`). The response carries a challenge that
links here:

```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="exe.dev", error_uri="https://exe.dev/docs/https-tokens-for-vms"
WWW-Authenticate: Basic realm="exe.dev"
Cache-Control: no-store
```

The `Basic` challenge is what prompts `git` to ask its credential helper for
the token. It is left out for a browser's `fetch` or `XMLHttpRequest`, which
would otherwise pop up a password prompt; those get the 401 too, so a page
can notice that its session ended. To send a browser to the login page
instead, navigate to the page, or request it with `Accept: text/html`.

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