Skip to content

Inspect tokens for external API clients - #1065

Merged
omehegan merged 2 commits into
buildkite:mainfrom
tamird:codex/buildkite-token-inspection
Oct 28, 2026
Merged

omehegan merged 2 commits into
buildkite:mainfrom
tamird:codex/buildkite-token-inspection

Conversation

@tamird

@tamird tamird commented Oct 22, 2026

Copy link
Copy Markdown
Contributor

bk auth token reads the selected stored credential, or BUILDKITE_API_TOKEN when set, and prints it without making an API request. If the stored OAuth access token has expired, this command does not trigger renewal, so another API client receives the expired token.

Add bk auth token --json to inspect the selected token through GET /v2/access-token, which returns details about the token used to authenticate the request 1. The existing transport can renew stored OAuth credentials after a 401 and retry the inspection. The JSON output pairs the bearer token from the final response request with that response's expiry and the selected organization. Reading the token from that request keeps the values together if the shared token source changes while the response is pending.

A successful inspection returns the token even when little lifetime remains. The result uses null when no expiry timestamp is available and does not classify the credential from that absence. The --timeout flag sets a 30-second default deadline for the inspection and any renewal requests; credential-store operations can outlast it. Raw bk auth token retains its current behavior.

@tamird
tamird requested review from a team as code owners October 22, 2026 15:59
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-22T16:05:14.061116Z 2574f28 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@tamird

tamird commented Oct 22, 2026

Copy link
Copy Markdown
Contributor Author

Clarify CLI OAuth token inspection expiry

Does GET /v2/access-token always include expires_at, and is it non-null for every access token issued to the Buildkite CLI OAuth application, including replacements issued by refresh? If the field can be absent or null, what does each case mean?

A proposed bk auth token --json mode calls this endpoint through the CLI's existing renewal transport and returns the bearer token from the final response request with that response's expiry. A caller can use the timestamp to decide when to obtain another token. The Go SDK decodes both an absent field and null as nil, so the command cannot distinguish those cases.

The REST documentation shows expires_at but does not define those cases 1. The device-authorization documentation says expires_in is present for applications with an expiry configured, including the lifetime used when refresh is enabled 2. The GraphQL APIAccessToken.expiresAt field defines null as no expiry 3.

tamird and others added 2 commits October 28, 2026 14:58
bk auth token reads the selected stored credential, or
BUILDKITE_API_TOKEN when set, and prints it without making an API
request. If the stored OAuth access token has expired, this command does
not trigger renewal, so another API client receives the expired token.

Add bk auth token --json to inspect the selected token through GET
/v2/access-token, which returns details about the token used to
authenticate the request [1]. The existing transport can renew stored
OAuth credentials after a 401 and retry the inspection. The JSON output
pairs the bearer token from the final response request with that
response's expiry and the selected organization. Reading the token from
that request keeps the values together if the shared token source
changes while the response is pending.

A successful inspection returns the token even when little lifetime
remains. The result uses null when no expiry timestamp is available and
does not classify the credential from that absence. The --timeout flag
sets a 30-second default deadline for the inspection and any renewal
requests; credential-store operations can outlast it. Raw bk auth token
retains its current behavior.

[1]: https://buildkite.com/docs/apis/rest-api/access-token
@omehegan
omehegan force-pushed the codex/buildkite-token-inspection branch from 95e3ba8 to 8dd652e Compare October 28, 2026 03:58
@omehegan

Copy link
Copy Markdown
Contributor

@tamird thanks for this PR! To answer your follow-up questions, I checked the server implementation: GET /v2/access-token always includes expires_at, with null meaning no stored expiry, and tokens issued through refresh-enabled OAuth flows have an expiry, including replacements issued by refresh. The PR’s handling looks right: return the timestamp when available and null otherwise, without inferring the token’s type or refresh capability.

@omehegan
omehegan merged commit da46422 into buildkite:main Oct 28, 2026
1 check passed
@tamird
tamird deleted the codex/buildkite-token-inspection branch October 28, 2026 13:19

tamird commented Oct 28, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for confirming the expiry behavior. Could you include this in the next CLI release? Our build client is ready to use it; v3.66.0 doesn't have bk auth token --json.

@omehegan

Copy link
Copy Markdown
Contributor

@tamird yep, this has just been released in v3.67.0.

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.

2 participants