> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Model

> Understand Nullspace API keys, preview tokens, private traffic tokens, desktop viewer tokens, SSH credentials, and file transfer URLs.

Nullspace uses separate token families for separate trust boundaries. Treat
every token-bearing URL or header value as a bearer credential unless this page
explicitly says it is only a marker.

The main families are API keys, edge preview tokens, preview continuation
cookies, preview proxy tokens, private traffic tokens, desktop viewer tokens,
SSH relay credentials, and file transfer URLs.

| Token family                 | Where it appears                                                                          | Use                                                                                             | Handling                                                                                          |
| ---------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| API keys                     | `Authorization: Bearer ...`, `NULLSPACE_API_KEY`, CLI auth config                         | Authorize SDK, CLI, MCP, and raw HTTP API calls.                                                | Store as account secrets. Do not put them in machine apps or browser URLs.                        |
| Edge preview tokens          | `edge_token` query parameter in direct preview URLs                                       | Bootstrap direct HTTP and WebSocket preview access for one machine, port, transport, and grant. | Treat the whole URL as a secret; rotate by requesting a fresh preview URL.                        |
| Preview continuation cookies | Scoped HTTP-only preview cookie set by Nullspace edge after direct HTTP preview bootstrap | Let normal browser navigation continue without preserving `edge_token` on every subpath.        | Browser-managed only. They do not authorize WebSocket upgrades.                                   |
| Preview proxy tokens         | `x-nullspace-preview-proxy-token` header for custom preview proxy upstream requests       | Authorize customer-run proxies to forward HTTP or WebSocket traffic to Nullspace edge.          | Keep in the proxy server, not in browser-visible URLs or client JavaScript.                       |
| Private traffic tokens       | `x-nullspace-traffic-access-token` header when `allow_public_traffic` is false            | Add private-traffic authorization on top of direct preview or proxy auth.                       | Store separately from preview tokens; proxy target responses only return the header name.         |
| Desktop viewer tokens        | Signed managed desktop viewer URLs                                                        | Authorize browser access to managed desktop streams.                                            | Treat viewer URLs as bearer credentials and rotate when sharing ends.                             |
| SSH relay credentials        | Short-lived OpenSSH certificate and matching private key                                  | Authorize SSH relay login.                                                                      | Keep the private key local; prefer `nullspace ssh` over legacy signed port-22 WebSocket fallback. |
| File transfer URLs           | Signed upload, download, and volume file URLs                                             | Allow direct file transfer without streaming through the SDK process.                           | Treat as short-lived bearer URLs and avoid logging them.                                          |

## Direct preview URLs

Direct preview URL helpers return signed URLs. The HTTP URL may set a scoped
preview continuation cookie after the first browser load, but the initial
signed URL remains a bearer credential. WebSocket preview clients must use the
signed `websocket_url`; HTTP continuation cookies are not accepted for
WebSocket upgrades.

Use the SDK redaction helpers or default CLI human output when showing preview
URLs in terminals, logs, or support artifacts. CLI `--json` and explicit raw
output modes are for automation and can contain bearer credentials.

Durable preview grants record token-redacted usage metadata and audit events:
status, expiry, first/last use, request/WebSocket/byte counters, last error
code, and operator disabled time. Operators can temporarily disable one grant
or preview traffic for a machine without exposing raw preview tokens.

## Custom preview proxies

Custom preview proxy targets return marker-only upstream URLs containing
`__ns_preview_transport=header`. That marker is not a secret. The proxy token
value is the secret and must be forwarded as
`x-nullspace-preview-proxy-token` on every upstream HTTP request or WebSocket
upgrade.

If private traffic is enabled, send the separate
`x-nullspace-traffic-access-token` header as well. Preview proxy tokens and
private traffic tokens are not interchangeable, and Nullspace strips both
headers before the request reaches the machine service.

## Related

* [Preview URLs](./preview-urls)
* [Custom preview proxy](./custom-preview-proxy)
* [Access control](./access-control)
* [WebSockets](./websockets)
* [SSH access](../access/ssh)
* [CLI reference](../reference/cli)
* [Python SDK reference](../sdk-reference)