# Access tokens

The ct CLI, the GDB bridge, CI jobs and scripts authenticate with personal access tokens. Each one belongs to one workspace, yours or an organization’s, and carries only the scopes you give it.

## Create a token

1. In the app, open [Settings](https://app.circuittwin.ai/app/settings) and find **Access tokens**.
2. Name the token after where it will live (a laptop, a CI project, an agent), choose its scopes and when it expires: 30 days, 90 days, one year, or never (until you revoke it).
3. Copy it. Tokens start with `ctk_` and are shown once; CircuitTwin stores only a hash.

## Scopes

| Scope  | Allows                                                                    |
| ------ | ------------------------------------------------------------------------- |
| twins  | Upload datasheets and documents, build and read twins, search the catalog |
| runs   | Projects, systems, firmware uploads and runs                              |
| suites | Submit and read test suites (CI needs runs and suites)                    |
| gdb    | Remote debug sessions through ct gdb-bridge                               |

A token can do at most what its scopes and your current role in the workspace both allow, checked on every request. Tokens can never create tokens or manage members.

## Use a token

your machine

```
ct login --server https://app.circuittwin.ai       # paste the token at the prompt
ct login --status
```

CI or a script

```
export CT_SERVER=https://app.circuittwin.ai
export CT_TOKEN="$CIRCUITTWIN_TOKEN"   # from a masked CI secret
```

> **Keep tokens out of the command line**
>
> ct never takes a token as an argument, because arguments end up in shell history and process listings. Use the prompt, `--token-stdin`, or `CT_TOKEN` from a secret store.

## Revoke a token

Revoke it in **Settings, Access tokens**. Every ct command checks the sign-in with the server, so the next command that uses the token fails, including local runs. On your own machine, `ct login --logout` forgets the stored token. See [Troubleshooting](https://circuittwin.ai/docs/troubleshooting) for sign-in errors.