> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/licensing/device-code-sign-in.md).

# Device-code sign-in

How telys login uses the RFC 8628 device-code flow to sign you in, register a device key, and fetch your offline license — with a headless path for CI.

`telys login` signs a machine in without handling your password. It uses the **OAuth 2.0 Device Authorization Grant** (RFC 8628): the CLI requests a code, you approve it in a browser, and Telys exchanges it for locally cached credentials. The result is a per-device identity — an Ed25519 key plus a device id — and a signed license the runtime verifies offline.

## Why a device-code flow

Telys often runs where there is no browser — a server, a container, an SSH session. A device-code flow fits:

* The CLI never sees your credentials — only a device code and, later, tokens scoped to this machine.
* Approval happens in a browser at [accounts.thyn.ai](https://accounts.thyn.ai), where MFA and SSO already work.
* Each machine gets its own key and id, so you can revoke devices independently. See [Seats & devices](https://docs.telys.ai/licensing/seats-and-devices.md).

## The flow, step by step

{% stepper %}
{% step %}

#### Start the login

```bash
telys login                    # free telys_developer plan
telys login --plan telys_pro   # commercial plan
```

The CLI requests a device code from the identity portal (`$TELYS_ACCOUNTS_URL`, default `https://accounts.thyn.ai`). It prints a user code and a verification URL and, unless you pass `--no-browser`, opens the URL.
{% endstep %}

{% step %}

#### Approve in the browser

Sign in at the verification URL and confirm the code shown by the CLI. Your account, plan, and any `telys_pro` Stripe checkout are handled here. The CLI polls the control plane (`$TELYS_API_URL`, default `https://api.telys.ai`) while it waits.
{% endstep %}

{% step %}

#### Register the device

On approval, Telys generates an **Ed25519 device key** and a random **device id**, and caches your control-plane credentials under `$TELYS_HOME` (default `~/.telys`):

```
~/.telys/device_key.pem     # Ed25519 private key for this device (0600)
~/.telys/device_id          # uuid4 hex identifying this device
~/.telys/token              # cached control-plane token
~/.telys/api_key            # cached API key
```

The private device key never leaves the machine; it identifies this device to your account.
{% endstep %}

{% step %}

#### Fetch the license

Telys downloads your signed license and caches it:

```
~/.telys/login_license.jwt  # signed, offline-verifiable license
```

This JWT records your `tier` and `features`; the runtime checks it offline from then on. See [Offline licenses & verification](https://docs.telys.ai/licensing/offline-licenses.md).
{% endstep %}
{% endstepper %}

Unless you pass `--no-install`, `telys login` also installs the signed runtime for your platform. To activate a tier without it, pass `--no-install` and run [`telys runtime install`](https://docs.telys.ai/cli/runtime.md) later.

## Headless & CI sign-in

On a machine with no browser — CI, a build agent, a remote box — provide a token directly:

```bash
telys login --token "$TELYS_TOKEN" --plan telys_pro --no-browser --no-install
```

`--token` authenticates with a control-plane token you already hold, skipping the browser; `--no-browser` stops the CLI opening a URL. Use this for automation.

{% hint style="info" %}
Pass the token through the environment (`$TELYS_TOKEN`), not the command line, to keep it out of shell history and CI logs. `$TELYS_TOKEN` overrides the cached control-plane token; `$TELYS_API_KEY` overrides the cached API key.
{% endhint %}

## Command reference

```bash
telys login [--token TOKEN] [--plan PLAN] [--no-install] [--no-browser]
```

| Flag            | Default           | Effect                                                                 |
| --------------- | ----------------- | ---------------------------------------------------------------------- |
| `--token TOKEN` | —                 | Authenticate headlessly with a control-plane token (skips the browser) |
| `--plan PLAN`   | `telys_developer` | The tier to activate (e.g. `telys_pro`)                                |
| `--no-install`  | off               | Do not install the signed runtime as part of login                     |
| `--no-browser`  | off               | Do not attempt to open a browser; print the URL instead                |

The relevant environment variables:

| Variable             | Default                    | Effect                                            |
| -------------------- | -------------------------- | ------------------------------------------------- |
| `TELYS_HOME`         | `~/.telys`                 | Root of all on-disk state (keys, license, tokens) |
| `TELYS_ACCOUNTS_URL` | `https://accounts.thyn.ai` | Identity portal for the device-code flow          |
| `TELYS_API_URL`      | `https://api.telys.ai`     | Control plane for keys, device, and license       |
| `TELYS_TOKEN`        | —                          | Control-plane token override                      |
| `TELYS_API_KEY`      | —                          | Telys API key override                            |

## Verify it worked

Confirm the runtime is installed and the license verifies locally:

```bash
telys runtime status     # 0 = ready, 1 = not installed
telys runtime verify     # verifies the installed runtime + license offline
```

See [Verify your install](https://docs.telys.ai/start-here/verify-install.md) for the full walkthrough.

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Offline licenses &#x26; verification</strong></td><td>What the license.jwt is and how it is checked.</td><td><a href="https://docs.telys.ai/licensing/offline-licenses.md">Offline licenses</a></td></tr><tr><td><strong>Seats &#x26; devices</strong></td><td>Your per-device key, and re-login on a new machine.</td><td><a href="https://docs.telys.ai/licensing/seats-and-devices.md">Seats &amp; devices</a></td></tr><tr><td><strong>License &#x26; login issues</strong></td><td>Fix a stuck or failing sign-in.</td><td><a href="https://docs.telys.ai/troubleshooting/license-and-login.md">License &amp; login</a></td></tr></tbody></table>

Next: [Offline licenses & verification](https://docs.telys.ai/licensing/offline-licenses.md).
