docs(security): document OAuth access tokens on the APIToken scheme#111
Merged
Conversation
Adds an OAuthAccessToken bearer scheme alongside APIToken and declares a global security requirement listing both as alternatives, wired into the client-bearing sources (merged + client). Enables first-class OAuth in the generated SDKs. Includes OAUTH_SDK_DESIGN.md describing the cross-SDK rollout. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This comment was marked as duplicate.
This comment was marked as duplicate.
Sorry, something went wrong.
aditya-scio
reviewed
Jun 15, 2026
There was a problem hiding this comment.
The core design here makes sense to me. The important insight is that this is fundamentally a spec-shape problem, not just a generator-flag problem the global security block plus flattenGlobalSecurity: false is what gets us to a sane client-level auth surface instead of scattered per-method args. The main thing I’d keep treating carefully is sequencing: publishing the spec before the SDK wrappers/hooks land would create avoidable churn, so the coordinated rollout note in the PR is important.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as duplicate.
This comment was marked as duplicate.
Sorry, something went wrong.
A Glean API token and an OAuth access token are both HTTP bearer credentials, so the existing single APIToken security scheme already covers both. No separate OAuth scheme, global security block, or flattenGlobalSecurity change is needed, and the SDKs keep their flat apiToken constructor field. - Drop the OAuthAccessToken scheme, the global security block, and the per-operation security removal. - Drop OAUTH_SDK_DESIGN.md (the heavyweight wrapper/hook plan). - Keep one action: update components.securitySchemes.APIToken.description. External-IdP OAuth tokens still require the X-Glean-Auth-Type: OAUTH request header, supplied by the caller. Glean-issued OAuth tokens (Authorization Server, incl. DCR) are detected by issuer with no header. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
steve-calvert-glean
changed the title
steve-calvert-glean
added a commit
to gleanwork/glean-developer-site
that referenced
this pull request
Jun 15, 2026
An OAuth access token is a bearer credential, so it goes in the existing apiToken field. Add an OAuth section to each SDK's Authentication docs covering the three tiers (Glean token; Glean-issued / Authorization Server OAuth, incl. DCR; external-IdP OAuth + the X-Glean-Auth-Type: OAUTH header) using each SDK's verified per-request header mechanism. Java uses a small custom HTTPClient since its builder has no per-request header option. Also correct two stale ActAs examples in the same sections: Python headers= -> http_headers=, and Go context.WithValue -> operations.WithSetHeaders. Supersedes the earlier draft of this PR, which injected both headers via a full custom HTTP client in every language. Pairs with gleanwork/open-api#111. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Merged
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A Glean API token and an OAuth access token are both HTTP bearer credentials, so the existing single
APITokensecurity scheme already covers both. This overlay now only clarifies theAPITokenscheme description to document OAuth usage — it no longer adds a second security scheme.What changed since the first draft
OAuthAccessTokenscheme, the globalsecurityblock, and the per-operationsecurityremoval.OAUTH_SDK_DESIGN.mdand the plannedflattenGlobalSecurity: false+ per-SDK wrapper/hook work.updatetocomponents.securitySchemes.APIToken.description.Why
The second scheme forced
flattenGlobalSecurity: false, which turned the flatapiTokenconstructor into a breaking change requiring a hand-authored shim in all four SDKs plus a coordinated rollout. Since both credentials are bearer tokens on the sameAuthorizationheader, none of that is necessary:apiTokenapiToken; detected by issuer, no extra headerapiToken+ theX-Glean-Auth-Type: OAUTHrequest header, supplied by the caller (a per-request header option on the SDKs, or a custom HTTP client)This is a description-only spec edit; it does not change SDK generation behavior.
Follow-up
SDK usage is documented in the api-client pages on the developer site (gleanwork/glean-developer-site).