# Teammates and tokens

> Let colleagues and agents deploy with a personal, scoped, revocable token instead of SSH, never stronger than their roles.

Colleagues and agents deploy with a token, over HTTPS, while only the owner holds SSH to the server. A token can be revoked at any time, and never does more than its holder's roles.

```diagram
[Your laptop] sitesolide deploy
-> HTTPS, with your token
[Dashboard] https://dashboard.<zone>
-> checked against your roles
[Your app] deployed, no SSH key involved
```

## Before you begin

- Company sign-in, set up by the owner: see [Access and sign-in](access.md#set-up-company-sign-in).
- A Developer or Admin role on a project, or the right to create projects, which the owner grants with `sitesolide people <email> --may-create`. A Viewer mints no token.

## Create a token

1. Open `https://dashboard.<zone>` and go to **Tokens**.
2. Click *Unlock to create*, and sign in again with your provider.
3. Click *New token*, give it a **Name**, and tick the **Projects it may deploy**.
4. Tick the **Permissions** it needs, choose when it **Expires**, then click *Create token*.
5. Copy the token, which starts with `sst_`. It is shown once.

The owner creates tokens the same way, for their own agents or for someone in **People**, and unlocks with the dashboard's password.

## Pick its permissions

| Option | Lets the token | Needs you to be |
|---|---|---|
| Projects it may deploy | Deploy, read logs, restart. | Developer or Admin there. |
| New projects | Create projects, which make you their Admin. | Granted the right to create. |
| Deploy public sites | Deploy a site anyone opens. | Admin of every project it reaches. |
| Use outbound network | Use `"network": "outbound"` or `egress`. | Admin of every project it reaches. |
| Declare a domain | Write `domain` in `sitesolide.json`. | Admin of every project it reaches. |
| Manage secrets | List names, set and remove variables. | Developer or Admin there. |

The server checks your roles at every request: lowered to Viewer on a project, your token stops deploying it.

## Sign in on your workstation

```bash
sitesolide login --url https://dashboard.<zone>
```

It asks for the token without echoing it, checks it, and keeps it in `~/.config/sitesolide/secrets/`.

```text
-> signed in to https://dashboard.example.com
   projects: notes
```

## Sign in an agent

In a sandbox, set both variables, which together win over the files:

```bash
export SITESOLIDE_API=https://dashboard.<zone>
```

```bash
export SITESOLIDE_TOKEN=<token>
```

## Deploy with the token

From the project's folder:

```bash
sitesolide deploy
```

A token runs `deploy`, `status`, `logs`, `share`, `secrets` and `restart`. Other commands, and `deploy --dry-run`, need the owner's SSH. A project the token creates is Restricted unless it may deploy public sites. A static site cannot be Restricted, so creating one needs that permission.

## Check it worked

`sitesolide status` lists the projects your token reaches, their service and their general access.

```bash
sitesolide status
```

## Revoke a token

On **Tokens**, click *Revoke* on its row, then *Revoke token*. No unlock is needed, and the next request with it is refused.

Your tokens are revoked too when you no longer sign in to the dashboard. A person holds ten live tokens at most.

## Next steps

- [Access and sign-in](access.md): give people the roles their tokens follow.
- [Secrets](secrets.md): set variables with a token that may manage secrets.
- [Agents](agents.md): let an agent deploy with its own token.

Full reference: https://github.com/cthiriet/sitesolide/blob/main/docs/access.md#your-own-tokens