[HWORKS-3005] Document the API key scopes - #646
Open
jimdowling wants to merge 7 commits into
Open
Conversation
https://hopsworks.atlassian.net/browse/HWORKS-3005 The API key guide told the reader to "select the required scopes" but nothing in the docs said what any scope grants, so the only way to find out was to read the @ApiKeyRequired annotations in hopsworks-ee or hit a 403 320004 and read the scope name out of the error. Add a reference page listing every scope with the endpoint groups it unlocks, which scopes are privileged, which scopes each account role may select, the scopes hops setup grants, and what the 320004 error looks like. Link it from the create-key guide and the projects index, and add it to the nav under Api Keys. Signed-off-by: Jim Dowling <jim@logicalclocks.com> Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
https://hopsworks.atlassian.net/browse/HWORKS-3005 The command blocks in .claude/CLAUDE.md (AGENTS.md is a symlink to it) and .claude/docs/README.md still installed from a requirements-docs.txt that no longer exists and built with a hand-made docs/javadoc stub, which fails strict mode with a nav warning. CI uses the repo's own uv project and hopsworks-docs CLI, so list those: uv sync --extra cli, the sibling hopsworks-api install, and hopsworks-docs check / serve / markdownlint / snakeoil / linkchecker. Signed-off-by: Jim Dowling <jim@logicalclocks.com> Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
https://hopsworks.atlassian.net/browse/HWORKS-3005 hopsworks-ee removes both scopes, since no endpoint ever accepted them, so the reference no longer lists them as reserved and the service-user row no longer excludes KUBE. Signed-off-by: Jim Dowling <jim@logicalclocks.com> Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
jimdowling
marked this pull request as ready for review
September 3, 2026 11:30
…-scopes # Conflicts: # .claude/CLAUDE.md # .claude/docs/README.md
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.
The API key guide told the reader to "select the required scopes" but nothing in the docs said what any scope grants; the only sources were the
@ApiKeyRequiredannotations in hopsworks-ee or the scope name inside a403 320004error.Adds
user_guides/projects/api_key/api_key_scopes.md: a reference table of everyApiScopeand the endpoint groups it unlocks, which scopes are privileged (HOPS_ADMINonly), which scopes each account role may select, the scopes ahops setupkey carries, and what the320004error looks like. Linked from the create-key guide and the projects index; nav entry under Api Keys.The
hops setupscope list matches logicalclocks/hopsworks-ee#3264 after its 2026-09-03 follow-up commit, which addsKAFKA,PYTHON_LIBRARIES,GIT,TRINOandSUPERSETto the token-flow defaults.Verification
markdownlint-cli2on the three changed pages: 0 issues.hopsworks-docs check(strictmkdocs build -s, the CI gate): passes locally with the Python client installed from the siblinghopsworks-apicheckout.@ApiKeyRequired(acceptedScopes = ...)annotations across every resource underhopsworks-api/src/main/javain hopsworks-ee at the HWORKS-3005 branch head.🤖 Generated with Claude Code