# Read tokens

> Create API tokens that read from private repositories.

Source: https://docs.telesphorepo.com/security/read-tokens/

A **read token** lets a script, build or package manager read from a private repository without your password. A read token never publishes. Writes need a [publish session](/publishing/overview/).

A token looks like this:

```text
trp_a1b2c3d4e5f6_<secret>
```

The server stores only a SHA-256 hash of the secret.

## Create a token

1. Open the **Read tokens** page (`#/tokens`).

2. Enter a name. The name must be unique among your tokens.

3. Optional: enter a number of days. The token then expires. Without a value, the token never expires.

4. Copy the token. The server shows it once.

You can also use the API. This call needs a UI session or Basic auth with your password:

```sh
curl -u alice:PASSWORD -X POST https://repo.acme.com/api/tokens \
  -H 'Content-Type: application/json' \
  -d '{"name":"ci-read","expires_in_days":90}'
```

The answer holds the `token` field. `expires_in_days` must be between 1 and 36500.

## Use a token

Use the token as the Basic auth password. The username can be anything.

- curl

  ```sh
  curl -u ci:trp_a1b2c3d4e5f6_SECRET \
    https://repo.acme.com/maven/releases/com/acme/app/1.0/app-1.0.pom
  ```

- Gradle

  ```kotlin
  repositories {
      maven {
          url = uri("https://repo.acme.com/maven/releases")
          credentials {
              username = "ci"
              password = providers.environmentVariable("TR_READ_TOKEN").get()
          }
      }
  }
  ```

- Maven

  ```xml title="~/.m2/settings.xml"
  <server>
    <id>acme</id>
    <username>ci</username>
    <password>${env.TR_READ_TOKEN}</password>
  </server>
  ```

- apt

  ```text title="/etc/apt/auth.conf.d/acme.conf"
  machine repo.acme.com login ci password trp_a1b2c3d4e5f6_SECRET
  ```

A token has the read permission of its owner. It sees the repositories that the user can read. It also works on the read routes of `/api/`, such as `/api/me`.

## Revoke a token

Delete the token on the **Read tokens** page. It stops working at once. Via the API:

```sh
curl -u alice:PASSWORD -X DELETE https://repo.acme.com/api/tokens/5
```

The page also shows when each token was last used. The server updates this value at most once per minute.

## Gotchas

- **A token cannot publish.** A write without an open publish session gets 401 and a message that points to publish sessions.
- **A token cannot create tokens.** You need a UI session or your password.
- **SSO users cannot create tokens.** They have no password, so they cannot use Basic auth. Use a local account for automation.
- **Anonymous repositories need no token.** If a repo has `anonymous_read` on, anyone can read it.
- **A disabled user fails authentication.** Their tokens stop working.
- **Keep tokens out of logs.** Telesphorepo never logs them. Make sure your CI does not print them either. Use masked secrets.