> 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/troubleshooting/license-and-login.md).

# License & login

Fix a failed telys login, an expired or invalid license, a wrong-plan account, and headless sign-in with --token in CI or over SSH.

`telys login` uses a browser **device-code** flow (RFC 8628) by default: it prints a code, you approve it at the accounts portal, and Telys caches your credentials and license under `$TELYS_HOME` (default `~/.telys`). Most login problems are a browser that won't open, a stale or expired license, or the wrong plan. All are fixable from the CLI.

{% hint style="info" %}
Login writes `token`, `api_key`, `device_key.pem`, `device_id`, and `login_license.jwt` under `~/.telys`. When in doubt, sign in again — it refreshes all of them.
{% endhint %}

## Quick check

```bash
telys login             # sign in (free telys_developer by default)
telys runtime verify    # confirms the cached license is valid and trusted
```

## Errors and fixes

<details>

<summary>Login fails or hangs — the browser never opens</summary>

The device-code flow opens your default browser to the accounts portal. On a headless host, over SSH, or in a locked-down desktop, that can fail silently.

**Cause:** no usable browser on this machine, or the environment blocks launching one.

**Fix:** skip the auto-open and approve the code manually, or switch to a token (next entry).

```bash
telys login --no-browser   # prints the code + URL; approve it on any device
```

Open the printed URL on any machine with a browser, enter the code, and the CLI completes on approval. Portal: `https://accounts.thyn.ai`.

</details>

<details>

<summary>Headless / CI sign-in with <code>--token</code></summary>

CI, containers, and bare SSH sessions have no browser, so the device-code flow can't complete interactively.

**Cause:** you need non-interactive sign-in.

**Fix:** pass a control-plane token directly. Keep it in an environment variable, never inline in a script.

```bash
telys login --token "$TELYS_TOKEN"                 # non-interactive
telys login --token "$TELYS_TOKEN" --no-install    # sign in now, install the runtime later
```

Set `$TELYS_TOKEN` (control-plane auth) or `$TELYS_API_KEY` (API key) to override cached credentials for a single command.

</details>

<details>

<summary>Expired or invalid license</summary>

The cached license is a signed offline token. Verification (RS256, offline) checks the issuer, audience, version, and expiry with a small grace window, and rejects an aged-out or tampered token.

**Cause:** the license expired, the clock is wrong, or the cached `login_license.jwt` is stale.

**Fix:** sign in again to refresh the license, then re-verify.

```bash
telys login             # refreshes ~/.telys/login_license.jwt
telys runtime verify    # re-checks iss / aud / ver / exp
```

If it still fails after a fresh login, the problem is in the token's claims or the verify keys — see the dedicated page.

Next: [Signature verification failures](https://docs.telys.ai/troubleshooting/signature-verification.md)

</details>

<details>

<summary>Wrong plan — feature or activation refused</summary>

You're signed in, but on a tier that doesn't grant the operation. `telys login` defaults to the free `telys_developer` plan (1 device).

**Cause:** you need a commercial tier (for example `telys_pro`) but signed in on `telys_developer`.

**Fix:** sign in with the plan you want, or upgrade in the portal first, then sign in again.

```bash
telys login --plan telys_pro         # commercial plan — subscribe via Stripe checkout
telys login --plan telys_enterprise  # sales-assisted
```

Tiers: `telys_developer` (free, 1 device) · `telys_pro` (commercial) · `telys_enterprise` (sales) · `telys_team` (self-host / `telys serve`). Manage subscriptions at `https://accounts.thyn.ai`; pricing at `https://telys.ai/pricing`.

</details>

## Next steps

If login succeeds but the runtime or license still won't verify, the problem is signature or claim checking, not sign-in.

<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>Signature verification failures</strong></td><td>Manifest, artifact, and license claim checks.</td><td><a href="https://docs.telys.ai/troubleshooting/signature-verification.md">Signature verification</a></td></tr><tr><td><strong>Device-code sign-in</strong></td><td>How the RFC 8628 flow works, end to end.</td><td><a href="https://docs.telys.ai/licensing/device-code-sign-in.md">Device-code sign-in</a></td></tr></tbody></table>

Next: [Signature verification failures](https://docs.telys.ai/troubleshooting/signature-verification.md)
