api(service-tokens): document organisation service tokens - #999
Closed
sebartyr wants to merge 3 commits into
Closed
Conversation
Add a page covering organisation service tokens: scope and limitations,
the CRUD endpoints under /v2/organisations/{id}/service-tokens, token
creation fields, bearer and git-over-HTTP authentication, and security
boundaries.
Link the page from the API index and list service tokens alongside API
tokens and OAuth 1 in the API overview.
Replace app_id with the resources array, add the description field, and document the creation response along with the fact that the biscuit is only returned once, following the clever service-tokens implementation. Add a hidden note listing what to confirm before publishing: the token-api backend answering 502, and the CLI command set still being an unreleased draft PR.
👋` Review app deletedYou closed this PR and deleted the review app. |
sebartyr
force-pushed
the
api-service-tokens
branch
from
August 25, 2026 13:37
2dcc1e4 to
b04f841
Compare
Collaborator
|
This is already being done in #911, and aligned with integrations. |
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.
Adds a page documenting organisation service tokens, the Biscuit-based machine-to-machine credentials for CI/CD pipelines, monitoring tools and scripts.
Content
content/api/service-tokens.md: scope and limitations, the four endpoints under/v2/organisations/{id}/service-tokens, creation fields and response, bearer and git-over-HTTP authentication, security boundaries.content/api/_index.md: a card linking to the page.content/api/howto.md: service tokens listed alongside API tokens and OAuth 1, which moves that section from two authentication mechanisms to three.Why this stays a draft
Two things need to land before this can be merged, both tracked in an HTML comment at the top of the page:
The backend is unreachable in production. Every
/service-tokensendpoint answers502with{"id":21002,"message":"Failed to communicate with token service"}, in read as well as in write. The same OAuth 1 signature returns200on/v2/self, so authentication is fine and the failure is downstream, in thetoken-apidependency. Publishing now would document endpoints that fail for every reader.The CLI commands are not released.
clever service-tokens(create, get, list, revoke) lives in feat: add service-tokens command clever-tools#1080, still a draft. Its files claimsince: 4.8.0whilemasteris at 4.11.0, so that marker needs a refresh before it ships. The CLI section should be added here once it is released.Field naming to confirm
The request and response fields follow the implementation in that CLI PR rather than the original spec:
resources, an array of application or add-on IDs, where the spec described a singleapp_id. The response shape{ token, metadata: { id, expiredAt } }and the fact that the biscuit is only returned at creation also come from that code. Both need confirming against the API once it answers.Vale and markdownlint pass on the three files. Hugo was not available locally, so the build has not been verified; the page uses no shortcode.