Access tokens and sessions

The control API issues access tokens for one computer. A token is not a console cookie, an API key or a session secret. The data_url returned with a token is the actual data endpoint; clients should not construct a gateway host from the computer ID.

Issuance and expiry

POST /v1/computers/{id}/access with {scopes?, expires_in?} returns {token, data_url, scopes, expires_at}.
- scopes is a subset of exec (exec, processes, PTY, SSH tunnel, setup log), files, desktop, desktop:view, browser and ports. The computers:exec key scope authorizes all of them; a request can only narrow this set. An unknown data scope returns 400 invalid_request. The default is all six.
- expires_in is in seconds: default 900, minimum 60, maximum 3600. The token is bound to one computer and to the key's IP allowlist.
- The effective expiry is the earlier of now + expires_in and the expiry of the issuing API key, and may be less than 60 seconds away despite the request minimum.
A token is revoked within 5 seconds when the key is revoked, the computer is deleted or suspended, or POST /v1/computers/{id}/revoke-access is called.
revoke-access never lifts a block on a computer; only lifecycle recovery can. Suspending an account invalidates tokens issued before the suspension, and reactivation cannot revive them.
Small clock differences (a few seconds) are tolerated for "issued at" checks, but expiry is strict everywhere, including on open streams. The SDKs refresh access tokens at least 60 seconds before expiry, subject to the credential deadline.

Session and connection lifetimes

Session (pty_..., dsk_..., cdp_...): lives until expires_at, can be listed and revoked, and can mint connect tokens.
Connect token (cct_...): single-use, must be used within 60 s, opens one WebSocket. It is needed only by clients that cannot send an Authorization header (browsers). The SDKs and the CLI send the access token as a header instead. The 60-second deadline limits the handshake, not the socket duration; the authorization_expires_at of the grant limits the open socket.
Viewer links (desktop, for people) carry a session secret in the URL fragment. The viewer page uses it to mint connect tokens, so reloading the page works until the session expires or is revoked.
CDP sessions return a ws_url containing the session secret (Playwright and Puppeteer cannot add headers to every reconnect). It is valid until expires_at (at most 3600 s) and can be revoked.

API-key-derived desktop and CDP authorization expires at the earliest of the requested session duration, the parent access token's expiry and the issuing key's expiry. The returned expires_at is the effective deadline, even when fewer than 60 seconds remain. Grants inherit the parent's IP restrictions. No data API exchange extends a parent authorization. A PTY's expires_at describes how long the process and session are retained, not continuing access; the response also includes authorization_expires_at for the connection that was issued. A fresh access token can reattach to a surviving PTY and obtain a new connection deadline, but an old connect token or an expired session secret cannot. The gateway and the computer end streams at authorization expiry, including open WebSockets and streaming HTTP responses; process execution may continue.

Keep connection credentials private

Session-list responses are metadata and omit creation credentials. A viewer fragment, a CDP URL, a preview access URL and a one-use connect token have different consumers; do not interchange them. Never print a complete session creation response in a public log. Deleting a session or revoking access ends authority but does not mean that a retained background process was killed. See PTY streaming, Desktop streaming and Browser streaming.

Revoke sessions explicitly

This complete program uses an existing running desktop computer named by CE_COMPUTER_ID. It creates a view-only desktop session and a browser session, reads their list entries, and deletes each in cleanup with a check that it is gone. It keeps the one-use connect token private and makes no connection claim from issuance alone.

import os
from computeengines import Client

with Client() as client:
    computer = client.computers.get(os.environ["CE_COMPUTER_ID"])
    desktop = computer.desktop.viewer(mode="view", exclusive=False, expires_in=60)
    try:
        found = [s for s in computer.desktop.sessions.list().data if s.id == desktop.id]
        if len(found) != 1 or found[0].mode != "view" or found[0].exclusive:
            raise RuntimeError("View session changed authority")
        grant = computer.desktop.sessions.token(desktop.id)
        # The one-use grant is private. Minting it is not a successful connection.
        if not grant.connect_token:
            raise RuntimeError("Connect token was not returned")
        browser = computer.browser.create(expires_in=60)
        try:
            if not any(s.id == browser.id for s in computer.browser.sessions.list().data):
                raise RuntimeError("CDP session is missing")
        finally:
            computer.browser.sessions.delete(browser.id)
            if any(s.id == browser.id for s in computer.browser.sessions.list().data):
                raise RuntimeError("CDP session revocation is unconfirmed")
    finally:
        computer.desktop.sessions.delete(desktop.id)
        if any(s.id == desktop.id for s in computer.desktop.sessions.list().data):
            raise RuntimeError("Desktop session revocation is unconfirmed")
    print("Session creation, listing and explicit revocation verified")

Dory is in development; these pages describe the planned service and may change. Questions: support@computeengines.com.