Skip to content

Warn before the API token expires and explain refused tokens - #25

Merged
lnsp merged 1 commit into
masterfrom
token-expiry-warning
Nov 21, 2026
Merged

lnsp merged 1 commit into
masterfrom
token-expiry-warning

Conversation

@lnsp

@lnsp lnsp commented Nov 21, 2026

Copy link
Copy Markdown
Member

What

Makes token expiry visible in the CLI before RFC-0005 release 2 gives every existing user token an expiry 90 days after the upgrade.

  • Expiry warning. When a response carries Valar-Token-Expires (RFC 3339) and the token expires within 14 days, the CLI prints one warning per run to stderr, however many requests the command makes:

    Warning: your Valar token expires in 5 days, at 2026-11-26 02:05 UTC. Create a new token at https://console.valar.dev/api-tokens/new and use it with 'valar config endpoint set <endpoint> --token <token>' or VALAR_TOKEN.
    

    The console link is shown for api.valar.dev. Other endpoints get "in the Valar console". The token value is never printed.

  • Refused tokens. A 401 whose WWW-Authenticate error_description says the token expired or was revoked becomes an api.TokenRefusedError carrying that reason, and the error output adds how to replace the token:

    listing services: Unauthorized: token 3f2a... expired at 2026-11-20T10:00:00Z
    Create a new token at https://console.valar.dev/api-tokens/new and use it with 'valar config endpoint set <endpoint> --token <token>' or VALAR_TOKEN.
    

    JSON mode puts the same text in error.message. The exit code stays 4 (notAllowed). The reason comes from the header, so it shows even if the body isn't JSON. Other 401s ("unknown token", or the current platform's "invalid credentials") are unchanged.

  • Buffered requests and log streams (streamOnce) both handle the header and the challenge. A followed log stream still stops on a refused token rather than reconnecting.

  • One line in the README says that tokens expire and what the CLI prints.

Pairs with valar/platform#319, #321 and #322

The platform sets Valar-Token-Expires and the WWW-Authenticate reason in #321. #319 starts the 90-day expiry of legacy tokens. Release this CLI version before that platform release (2.14.0) is deployed, so users are warned from the first day of the 14-day window. Against today's platform the CLI behaves as before: neither header is sent.

Tests

  • api/token_test.go:
    • the expiry header is reported from requests, failed requests and streams, but not when it's missing or malformed;
    • the expired and revoked challenges become a TokenRefusedError with the endpoint, for requests and streams, including with a non-JSON body;
    • "unknown token", a 401 without a challenge and a 403 with one keep their usual errors.
  • cmd/token_test.go:
    • the warning's wording and window, and that it appears once per run (one notice per run, three requests against a test server, token not printed);
    • rounding of the time left;
    • reportError adds the hint in human and JSON output with exit code 4.

go vet ./... and go test ./... pass. I also ran a built binary against a local fake API. It printed the warning once with the service list and exited 0, and printed the expired-token reason with the hint and exited 4 (in JSON mode too).

A response with Valar-Token-Expires within 14 days prints one warning
per run to stderr: when the token expires and where to create a new one.
The console link is shown for api.valar.dev; other endpoints are pointed
at their console. The token itself is never printed.

A 401 whose WWW-Authenticate error_description says the token expired or
was revoked returns that reason as an api.TokenRefusedError, and the
error output adds how to replace the token, in human and JSON mode. The
exit code stays 4. Both buffered requests and log streams are covered.
@lnsp
lnsp merged commit ccf7e90 into master Nov 21, 2026
3 checks passed
@lnsp
lnsp deleted the token-expiry-warning branch November 21, 2026 02:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant