feat(api): drop OAuth device-flow endpoints + schemas from spec#531
Merged
Conversation
PR #527 added /v1/oauth/device_code, /v1/oauth/token, /v1/oauth/revoke endpoints + their request/response schemas to the spec. On review, those spec entries turn out to be redundant and contract-drifting: Zero code consumers in the BoxLite tree read the OAuth schemas: - Python/Node SDKs expose only api_key (PyBoxliteRestOptions / JsBoxliteRestOptions). Go/C SDKs have no REST surface at all. - The Rust SDK's refresh_oauth() in src/boxlite/src/rest/client.rs posts hand-coded RFC 8628 forms — never reads the spec. - The CLI's commands::auth::device::login() hand-codes RFC 8628 forms. Industry alignment — none of these put OAuth endpoints in their spec: Stripe, GitHub, DigitalOcean, Anthropic, OpenAI. Only identity-provider products (Auth0, Okta) co-locate. Their business is auth; ours isn't. The wire format is fully defined by published IETF RFCs: - RFC 8628 §3.1 — device authorization request/response - RFC 6749 §4.4 / §6 — token exchange + refresh - RFC 7009 — token revocation Restating those in OpenAPI adds maintenance churn with no precision gain — implementers follow the RFC either way. Contract-drift fix: PR #530's BoxliteOAuthController in apps/api returns 503 temporarily_unavailable on every /v1/oauth/* route because the real OAuth server isn't built. With the endpoints out of the spec, the gateway no longer promises something it can't deliver. When the @node-oauth/node-oauth2-server backend lands, that work will add both the controller and the spec paths in one coherent commit. Spec changes: - Remove /v1/oauth/device_code, /v1/oauth/token, /v1/oauth/revoke paths - Remove DeviceAuthorizationRequest/Response, OAuthTokenRequest/Response, OAuthRevokeRequest, OAuthError schemas - Update info.description to point at the IETF RFCs for the wire format - BearerAuth.description: keep the four-token-source list; soften blo_/blr_ prefix descriptions to reference the RFCs not specific paths
This was referenced May 15, 2026
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
1 participant
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
PR #527 added
/v1/oauth/device_code,/v1/oauth/token,/v1/oauth/revokeendpoints + their request/response schemas to the spec. On review, those spec entries are redundant and contract-drifting — this PR removes them.Why
No code consumers in the BoxLite tree read OAuth schemas from the spec:
PyBoxliteRestOptions)api_keyexposedJsBoxliteRestOptions)apiKeyexposedrefresh_oauth())commands::auth::device::login())Industry alignment — none of these put OAuth in their spec: Stripe, GitHub, DigitalOcean, Anthropic, OpenAI. Only identity-provider products (Auth0, Okta) co-locate. Their business is auth; ours isn't.
Two sources of truth. The wire format is fully defined by IETF RFCs:
Restating in OpenAPI adds maintenance churn with no precision gain.
Contract-drift fix. PR #530's
BoxliteOAuthControllerinapps/apireturns503 temporarily_unavailableon every/v1/oauth/*route because the real OAuth server isn't built. With the endpoints out of the spec, the gateway no longer promises something it can't deliver. (PR #530 has been amended in parallel to drop that controller too — see commit673d7550.) When the@node-oauth/node-oauth2-serverbackend lands, that work will add both the controller and the spec paths in one coherent commit.What stays
BearerAuthsecurity scheme (with the four-token-source description)GET /v1/meandPrincipalschemainfo.descriptionnote explaining the CLI's two paths (API key vs--webdevice flow) and pointing readers at the IETF RFCs for the wire formatboxlite auth login --webTest plan
python3 -c "import yaml; yaml.safe_load(open('openapi/rest-sandbox-open-api.yaml'))"passes/oauth/*paths, no OAuth schemas (schema count: 30 → schemas with oauth: [])boxlite serve+boxlite auth login --web --url http://localhost:8080)