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

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# Create automation tokens for agents and scripts

> Mint a scoped, expiring automation token (at-tok-…) so a coding agent or script can set up and manage your Tokios workspace through the API without your password.

An **automation token** lets a program act on your workspace the way you do in the dashboard: pair a connector, publish a model, create an API key, read usage. You mint it in **Settings**, choose exactly what it may do, and it expires on a date you pick. Hand it to a coding agent such as Claude Code or Codex, a CI job, or a script, and that program can run the whole setup unattended.

It is not an API key. An API key (`sk-tok-…`) lets a client call your models. An automation token (`at-tok-…`) lets a program manage the workspace, and it can never call a model with it. The two never cross.

> [!NOTE]
>
> Automation tokens act only on your own workspace. They can never change your password or email, show or share an API key, rotate a connector's token, read stored prompts, change request logging, or create other automation tokens. Those stay behind a signed-in dashboard session.

## Create a token

Only a workspace admin can create, list, or revoke automation tokens.

**1. Open Settings**

In the dashboard, open **[Settings](https://tokios.com/console/settings)** and scroll to **Automation tokens**. Click **Create token**.

**2. Name it after what will hold it**

Use a name you will recognize in the token list and on the rows it creates, for example `claude-code on my laptop` or `ci-deploy`.

**3. Pick a preset or choose scopes**

**Setup** is the right preset for an agent that installs the connector and gets your model callable. **Read-only** suits monitoring. **Full** grants every scope. Tick individual scopes for anything else. See [Scopes](#scopes) below.

**4. Pick an expiry**

Every token expires. Choose 1 hour for a one-off setup run, longer for a standing job. The maximum is 1 year.

**5. Copy the token once**

The token is shown exactly once. Copy it into the program's secret store or a shell variable. If you lose it, **Regenerate** it from the list; the old value stops working at once.

## Scopes

A scope is `resource:verb`. A `write` scope includes the matching `read`. Nothing includes `keys:rotate` or `models:reroute`.

| Scope | What it allows |
| - | - |
| `connectors:read` | List connectors and read their live status and host stats |
| `connectors:write` | Start pairing, approve, rename, revoke and delete connectors. Deleting a connector that still serves models also needs `models:reroute` |
| `models:read` | List models, deployments, model groups, prices, limits and connection info |
| `models:write` | Create, edit, pause and resume models; create, edit and delete model groups; set prices and auto-publish |
| `models:reroute` | Move an existing model to another connector, rename it, or delete it. Each one changes which machine receives that model's traffic, so it also needs `models:write` and is in no preset except **Full** |
| `keys:read` | List API keys (fingerprints and settings, never secrets) |
| `keys:write` | Create, edit, revoke and delete API keys (a newly created key's secret is returned once) |
| `keys:rotate` | Rotate an existing API key and receive its new secret. This takes the key over from whoever holds it, so it is in no preset except **Full** |
| `usage:read` | Read usage, spend and the request log (counts and metadata only) |
| `playground:run` | Run the playground and model health checks (sends prompts to your models) |

| Preset | Scopes |
| - | - |
| **Setup** | `connectors:read`, `connectors:write`, `models:read`, `models:write`, `keys:read`, `keys:write`, `playground:run` |
| **Read-only** | `connectors:read`, `models:read`, `keys:read`, `usage:read` |
| **Full** | every scope above |

A call outside the token's scopes returns `403` with the missing scope named in the error, so a program can tell you exactly which grant it lacks.

## Use a token

Send it as a Bearer token to the dashboard host, not the API host. Every management call lives under `https://tokios.com/account/`.

**macOS & Linux**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s https://tokios.com/account/connectors \
  -H "Authorization: Bearer at-tok-YOUR_TOKEN"
```

**Windows CMD**

```cmd theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s "https://tokios.com/account/connectors" -H "Authorization: Bearer at-tok-YOUR_TOKEN"
```

| Response | Meaning |
| - | - |
| `401` | The token is invalid, expired, or revoked, the admin who created it changed or reset their password, or the workspace or that admin is suspended. |
| `403` with `"scope"` | The token lacks that scope. |
| `403` "only available from the console" | The action is reserved for a signed-in dashboard session. No scope grants it. |
| `429` | More than 240 calls in a minute from this token, or too many failed token attempts from this address. A lockout covers every token from that address, valid ones included. Wait and retry. |

For the full list of calls and the order an unattended setup makes them in, see [Let a coding agent set up Tokios for you](/guides/agent-setup.md).

## Hand it to an agent

Create a token with the **Setup** preset and a 1-hour expiry, then start your agent on the machine that runs your model and send it this prompt:

```text theme={"theme":{"light":"github-light","dark":"css-variables"}}
Read https://docs.tokios.com/guides/agent-setup and follow it. The console base URL is https://tokios.com and the automation token is in the TOKIOS_TOKEN environment variable. Never print the token. My model server is Ollama on this machine. When you are done, give me the final report described on that page.
```

Set `TOKIOS_TOKEN` in the shell before you start the agent so the secret never appears in the conversation. The guide page tells the agent everything else.

## Manage tokens

Each row in **Settings** shows the token's scopes, fingerprint, expiry, and when and from which IP address it was last used.

* **Regenerate** replaces the secret. The old value stops working immediately and the new one is shown once.
* **Revoke** stops the token for good. Create a new one to replace it.
* **Delete** removes a revoked or expired token from the list.

Changing or resetting your password revokes every token you created. A token minted from a stolen session stops working as soon as you recover your account, and any standing job needs a new token afterwards.

Rows an automation token created carry a **via token** badge on the **Connectors**, **Models**, and **Keys** tabs, so you can always tell what a program did. The badge stays after the token is deleted.

## Keep tokens safe

* **Scope narrowly.** A Setup token that has finished its job should be revoked, not kept.
* **Expire soon.** Use 1 hour for interactive agent sessions. A long expiry belongs only to a standing job in a secret store.
* **Keep it out of transcripts.** Read it from a shell variable; never paste it into a chat with the agent.
* **Watch the badge and the last-used column.** If a token was used from an address you do not recognize, revoke it.
* **Know what a minted key means.** A token with `keys:write` can create an API key, and that key keeps working after the token expires. Someone who steals a 1-hour Setup token can mint a key with no expiry and call your models until you notice. After any agent run, open the **Keys** tab, look for rows marked **via token**, and revoke any you did not expect.
* **Grant `models:reroute` only when you need it.** Moving, renaming, or deleting an existing model changes which machine receives its traffic. A token that can also pair connectors could pair a machine its holder controls and move your model there. Setup never needs it: it creates models but never moves them.
* **Expect a shared address to share a lockout.** After 8 failed token attempts from one IP address, every token from that address is refused with `429` for 6 minutes, valid ones included. Agents behind the same office network, NAT gateway, or CI runner pool share that lockout. If one client keeps sending a bad token, stop or fix it instead of letting it retry in a loop.

> **[Agent-driven setup](/guides/agent-setup.md)**
>
> The step-by-step procedure an agent follows with a Setup token.

> **[API keys](/setup/api-keys.md)**
>
> The keys your clients use to call your models.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.