HTTPS Tokens for VMs
The 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 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:
ssh exe.dev ssh-key generate-api-key --vm=my-vm --label=deploy
You can also create VM tokens locally by signing with a different namespace.
How it works
VM tokens work just like API tokens, with two differences:
-
Namespace: The signing namespace is
v0@VMNAME.exe.xyz(instead ofv0@exe.dev), scoping the token to a specific VM. When usingssh-key generate-api-key --vm, this is handled for you. -
Ctx header: When a request is authenticated via token, the
ctxfield from the payload is passed verbatim to your VM's HTTP server in theX-ExeDev-Token-Ctxheader. 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 anX-Exedev-Authorization: Bearer <token>HTTP header. The proxy consumes and strips this header before forwarding to your VM. - Bearer token in
Authorization(deprecated): Add anAuthorization: Bearer <token>HTTP header. PreferX-Exedev-Authorizationfor new integrations. - Basic auth: Username is ignored; password is the token. This works with tools like
gitthat 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 IDX-ExeDev-Email: Your email addressX-ExeDev-Token-Ctx: Thectxfield 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.
echo "$TOKEN" > ~/.ssh/exe_dev_token
git config credential.helper '!f() { echo "password=$(cat ~/.ssh/exe_dev_token)"; }; f'
git clone https://myvm.exe.xyz/repo.git