{
  "slug": "bk-auth-token-json-inspects-the-token-used-for-an-api-request-78f08683f88d",
  "title": "bk auth token --json inspects the token used for an API request",
  "tools": [
    "bk"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-10-29T05:39:14.000Z",
  "announced_at": "2026-10-29T05:39:14.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When an external API client needs the selected token and its expiry, run `bk auth token --json` to inspect it and emit JSON. The inspection can renew stored OAuth credentials after a 401 and retry.",
    "examples": [
      "bk auth token --json"
    ],
    "gotchas": [
      "Version: v3.67.0",
      "Non-interactive: Writes JSON to stdout. Without a token, returns an error advising `bk auth login`; credential-store operations can outlast the timeout.",
      "--json: Inspect token through API transport; emit token, expiry, and organization as JSON.",
      "--timeout: Sets inspection and renewal request deadline; default 30s, must be positive with `--json`.",
      "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.",
      "Credential-store operations can outlast the timeout deadline."
    ]
  },
  "why_it_matters": "Inspect the selected credential for an external API client, including a renewed stored OAuth credential when needed.",
  "before": "Run `bk auth token` to read the selected stored credential or `BUILDKITE_API_TOKEN` without an API request; an expired stored OAuth token is returned without renewal.",
  "sources": [
    "https://github.com/buildkite/cli/releases/tag/v3.67.0",
    "https://github.com/buildkite/cli/pull/1065",
    "https://github.com/buildkite/cli/blob/v3.67.0/cmd/auth/token.go"
  ],
  "rank": 0.95035,
  "review_state": "approved",
  "provenance": {
    "run_id": "daily-20261029-12",
    "verdict_id": "daily-20261029-12:daily-20261029-12-43371926afe5ec79-7:gate",
    "evidence_hash": "19fa2f053c99f70ec44d67b5c91dbd5bd38c9adb36cfe0c34d1c0cf3bade45a7"
  }
}