plexsphere

Appearance

Rotate service API tokens ​

API tokens (psk_…) authenticate a workload as a User or ServiceIdentity. plexctl identity-tokens wraps /v1/auth/tokens. The plaintext is shown exactly once — capture it on issue/rotate.

Prerequisites ​

Steps ​

Issue a token ​

shell
plexctl identity-tokens issue \
  --identity-ref service:<service-uuid> \
  --env-prefix prod \
  --ttl 720h
# WARNING: this is the only time this plaintext will be displayed
# psk_prod_…
# ID  ENV   CREATED_AT  EXPIRES_AT  LAST_USED_AT  ROTATED_AT
# …   prod  …           …           -             -

--identity-ref is user:<uuid> or service:<uuid>. The response prints the plaintext once under a one-time-plaintext banner; pipe it straight to the consuming secret store.

List and revoke ​

shell
plexctl identity-tokens list
plexctl identity-tokens delete --id <token-uuid>

list never returns plaintext.

Rotate a token ​

shell
plexctl identity-tokens rotate --id <token-uuid>

Rotate returns a fresh plaintext once and invalidates the old value. Roll the new value out before the response leaves your terminal.

Mint an OAuth2 service token ​

shell
plexctl identity-tokens issue-service \
  --client-id <client> \
  --grant-type client_credentials \
  --client-secret @/tmp/client-secret \
  --scope "domains:read"
# TOKEN_TYPE  EXPIRES_IN  SCOPE         ACCESS_TOKEN
# Bearer      3600        domains:read  ***

Verification ​

shell
plexctl identity-tokens list --output json | jq '.[] | {id, expires_at}'
# {
#   "id": "…",
#   "expires_at": "…"
# }

The rotated token's id is unchanged; its expires_at advances.

See also ​