docs: scopes, and what connecting an app grants - #81
Merged
Conversation
The page said the server gives a client 10 tools. It is more than that, and the number was already wrong twice — dropped rather than replaced, since a count in prose goes stale every time the surface changes. Adds where connected apps are managed and what revoking actually does, including the part that can surprise: the grant and every stored token go immediately, but an access token the app already holds stays valid until it expires, under an hour.
…mes one A public API that refuses a caller by naming a scope has to document what the scopes are, and there was nowhere to look them up — the word appeared zero times across quickstart, sdk, cli and build-with-ai. Covers the six resources and their read and write scopes, that write includes read, that self-description is never scoped, how to narrow a key at creation and the two limits every key has, what a consent screen is asking and that a grant is bound to one workspace, and the insufficient_scope response with its WWW-Authenticate header. SHIPS WITH ENFORCEMENT, not before. The 403 section describes behaviour production does not have yet: scopes are recorded and reported today, and refused once SCOPE_ENFORCEMENT is on. See the rollout runbook in the monorepo.
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.
Scopes went live on the API today. Two commits:
8c7b51ccorrects the MCP page, which claimed the server gives a client 10 tools (it is more, and the number had already been wrong twice, so it is gone rather than replaced), and adds how to review and revoke a connected app including the one-hour caveat on a token it already holds.40f1ea5addsconcepts/scopes.mdx: the six resources and their read/write scopes, write includes read, self-description is never scoped, narrowing a key at creation and the two limits every key has, what a consent screen asks, and the insufficient_scope response with its WWW-Authenticate header.The changelog entry published today links to
/docs/concepts/scopes, so this needs to land for that link to resolve.All four repo validators pass: frontmatter, nav and redirects, plan limits, webhooks.