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.

A token looks like this:

trp_a1b2c3d4e5f6_<secret>

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

Create a token

Open the Read tokens page (#/tokens).
Enter a name. The name must be unique among your tokens.
Optional: enter a number of days. The token then expires. Without a value, the token never expires.
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:

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 -u ci:trp_a1b2c3d4e5f6_SECRET \
  https://repo.acme.com/maven/releases/com/acme/app/1.0/app-1.0.pom

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

<server>
  <id>acme</id>
  <username>ci</username>
  <password>${env.TR_READ_TOKEN}</password>
</server>

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:

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.