# Tokens and sign-in

> Give CI, coding agents and your other computers API keys of their own, with a role, limited to their own sandboxes if you like, expiring, and revocable at once. Sign a computer in with a code.

`cloudex deploy` makes one admin key, which can do everything. Access tokens are API keys of their own for everything else that uses your deployment: a CI job, a coding agent, a second computer, a teammate. Each has a role, can be limited to the sandboxes it makes, can expire, and stops working the moment you revoke it.

```sh
cloudex tokens create ci --own --expires 90d   # prints the secret once
cloudex tokens                                 # lists them, with when each was last used
cloudex tokens revoke tk-a2b3c4d5              # it stops working at once
```

A token works wherever the admin key does: as `CLOUDEX_API_KEY` for the CLI and [SDKs](https://cloudex.build/docs/sdk.md), or as the bearer token for the [API](https://cloudex.build/docs/api.md#authentication).

## Roles

| Role | Can |
|---|---|
| `admin` | Everything, including tokens, [provider keys](https://cloudex.build/docs/keys.md) and adding and removing [nodes](https://cloudex.build/docs/nodes.md) |
| `user` (default) | Everything to sandboxes and [named saves](https://cloudex.build/docs/saves.md): make, connect, exec, agents, files, preview links, settings, forks. List nodes and make sandboxes on them. Not tokens, provider keys, or adding and removing nodes. |
| `read` | List sandboxes, saves and nodes, show them, read agent events, command output and files. No exec, SSH, preview links or changes. |

`--own` limits a `user` or `read` token to the sandboxes it makes, and forks of them. It doesn't see other sandboxes at all: `cloudex ls` leaves them out, and naming one gets "no sandbox named …". It can start from any named save, as [`cloudex run --from`](https://cloudex.build/docs/commands.md#ci-jobs-cloudex-run) does, but not make, replace or delete one, since other sandboxes start from saves. Sandboxes made with the admin key, or another token, belong to no own-only token.

An own-only token can't make sandboxes on a [node](https://cloudex.build/docs/nodes.md) whose isolation is plain Docker, or none: CI runs code from pull requests, and code that escapes its container there is root on the node. It can use nodes with Sysbox. It sees every node in the list.

`--expires` takes a time such as `12h`, `30d` or `never` (the default). An expired token stops working, and `cloudex tokens` stops listing it.

Only the admin key or an `admin` token can make, list and revoke tokens.

## Sign in another computer

On a computer without a key, `cloudex login` asks your deployment for a token and shows a code:

```text
$ cloudex login --url https://cloudex-api.example.workers.dev
To sign this computer in, run this on a computer that already uses https://cloudex-api.example.workers.dev:

  cloudex tokens approve BCDF-GHJK

Waiting for it (the code works for 10 minutes; Ctrl-C to stop)...
```

On a computer that already uses the deployment, approve it:

```sh
cloudex tokens approve                       # lists the sign-ins waiting
cloudex tokens approve BCDF-GHJK             # shows where it comes from, and asks
cloudex tokens approve BCDF-GHJK --own --expires 7d
cloudex tokens deny BCDF-GHJK
```

The new computer gets a token of its own, named after it (`--name` on `cloudex login` changes that), which expires in 90 days unless `--expires` says otherwise. Its role is `user`, or `read` if it asked for `read` with `--role`; it gets `admin` only when `--role admin` on `approve` says so, whatever it asked for, and `approve` says what it asked for. Only approve a code you started yourself: whoever has the other computer gets the token.

`cloudex login` also prints a link, `<API URL>/login?code=BCDF-GHJK`, that approves the code in the [dashboard](https://cloudex.build/docs/dashboard.md#sign-in), which shows the same details first.

`cloudex login --key` asks for a key instead, and a key in `$CLOUDEX_API_KEY` or on standard input is used as it is, as before.

## Dashboard sessions

A browser signed in to the [dashboard](https://cloudex.build/docs/dashboard.md) has a session, a token of the kind `session`, which `cloudex tokens` lists with a name such as `dashboard (Safari on macOS)`:

- **Role:** it has the role of whatever signed it in.
- **How long it lasts:** 30 days from its last use. One signed in with a code never lasts past the expiry chosen when it was approved.
- **Revoking it** signs that browser out at once. Its open terminals and desktops close within a minute.
- **It can't sign in anything else:** a session can't make a dashboard link or another session.
- **A session signed in with a token** acts for that token, reaching the same own sandboxes, and goes when the token is revoked.

## Coding agents and CI

An agent on your computer that needs its own access can sign in the same way. With `--json`, `cloudex login` prints the code as its first line, so the agent can show it to you while it waits:

```sh
cloudex login --url https://cloudex-api.example.workers.dev --json
# {"approveWith":"cloudex tokens approve BCDF-GHJK","expiresIn":600,"userCode":"BCDF-GHJK"}
```

For CI, make an own-only token and give the job your deployment's URL and the token as secrets:

```sh
cloudex tokens create github-actions --own --expires 90d
```

```yaml
- run: curl -fsSL https://cloudex.build/install | CLOUDEX_INSTALL_DIR="$HOME/.local/bin" sh
- run: ~/.local/bin/cloudex run --from node-base -- npm test
  env:
    CLOUDEX_API_URL: ${{ secrets.CLOUDEX_API_URL }}
    CLOUDEX_API_KEY: ${{ secrets.CLOUDEX_TOKEN }}
```

The job can then start, use and delete its own sandboxes, and nothing else.

## How it works

- A token's secret looks like `cx_a2b3c4d5_…`. Your deployment keeps only its SHA-256, in its D1 database, so a copy of the database lets nobody in. The secret is shown once, when the token is made.
- Every request reads the token's row, so a revoked token fails on its next request. An open terminal, desktop or `cloudex ssh` connection checks about once a minute, and closes once its token is revoked or expires. `cloudex tokens` shows when each was last used, to the minute.
- Tokens don't depend on the admin key: they keep working after `cloudex deploy --yes` replaces it.
- Device sign-in follows [RFC 8628](https://www.rfc-editor.org/rfc/rfc8628). Codes last 10 minutes, and up to 20 can wait at once, 3 from any one address. The approver sees the computer's name, address and country.
- `cloudex status` says which token this computer uses. The [API](https://cloudex.build/docs/api.md#endpoints) and [SDKs](https://cloudex.build/docs/sdk.md) make and revoke tokens too.
