TCM Automation Docs

Authentication

Automation clients authenticate with Personal Access Tokens (PATs).

Why PATs and not username/password

The web UI uses short-lived JWTs (15 minutes), refreshed transparently in the browser. That model is wrong for CI: a 15-minute token expires before most pipelines finish, and storing a password in a CI secret means the token is the password — rotating it later means changing your login.

A PAT is a long-lived, revocable credential bound to a specific user. Revoking it immediately disables the CI job, without forcing the user to change their password.

Token format

Every PAT looks like tcm_pat_<random>. The tcm_pat_ prefix lets the server tell PATs apart from JWTs in one byte-comparison; the random portion is 32 base64url-encoded bytes (~256 bits of entropy).

How to mint one

  1. Log into TCM as the user whose role the automation should run with.
  2. Open the avatar menu → API Tokens.
  3. Click New token, set a name and (optional) expiration.
  4. Copy the full plaintext token from the dialog — it is not shown again.
Treat the plaintext like a password
The token grants the same access as the user’s normal login, scoped to their tenant and role. Store it in your CI secret manager. Don’t commit it.

Using a token

Send the PAT in the standard Authorization: Bearer ... header on every request, exactly like a JWT:

curl -H "Authorization: Bearer tcm_pat_..." \
     $TCM_BASE_URL/api/v1/runs/$TCM_RUN_ID

Roles & permissions

A PAT does not embed a role. Every request looks up the owning user’s current role at evaluation time, so:

  • If you change a user’s role, their PATs follow immediately.
  • If you suspend the user, their PATs stop working without revocation.
  • Tokens never escalate beyond what the user can do in the UI.

Revoking

On the same API Tokens screen, hit Revoke next to a token. Revocation is immediate — the next API call from that token returns 401 token_revoked.

Only the user who owns a token can revoke it. (Tenant admins can disable the user instead, which has the same effect on every PAT they own.)

Expiration

Tokens may have an optional expiration. After the timestamp passes, the API responds 401 token_expired. Tokens without an expiration are valid until explicitly revoked — useful for long-lived runners, but rotate them periodically in line with your security policy.