docs(api): state what the API does today for logout, anonymous reads, tokens, pagination and errors - #870
Merged
Conversation
… tokens, pagination and errors Eight factual corrections to the API guide, each checked against the contract, the code or an annotated test, none changing a product promise (CP bugs/OW-065). - Anonymous reads: the guide named five credential-free operations and two anonymous reads; the handlers answer eight. The three it omitted (permissions:registry, sso/providers/enabled, the SSO redirect pair) are listed with what each returns and what the registry never returns. - Credential scope: scope_id is required for host scope and forbidden for system scope (credential.validate, api-credentials AC-03). The matching description on the contract's create schema lands with the OW-011 contract change, which regenerates code under annotated tests. - Pagination: the five cursor-paginated lists are named once, with the rule that next_cursor becomes the next request's cursor. - Environment overrides: the loader is a fixed allowlist, not a generic form; the guide now says so and links the reference. - Audit export: documented beside the list, with its filters, the 10,000-row cap and the truncation header, and the fact that it drops correlation_id and ignores unknown parameters (bugs/OW-064). - Errors: the three plain-text responses the service generates today are named (bugs/OW-063), and clients are told to expect non-JSON bodies from intermediaries regardless. - Authentication: API tokens are the automation credential and password login is interactive; the example reads the password from a file, uses --fail-with-body so a 401 cannot become TOKEN=null, sets expires_at, and names the revoke route. One sentence on the CSRF header for cookie callers. - Logout: the row says it revokes the cookies it is given and does nothing for a Bearer caller today (bugs/OW-062). Unresolved behavior is described as unresolved and named by request; nothing here presents it as fixed. The detect-secrets baseline is the hook's own line-number refresh.
github-actions
Bot
added
documentation
… introspection GET /api/v1/auth/me/permissions answers an anonymous caller with is_anonymous true and an empty list, found while classifying every operation for OW-011 (#873). It exposes nothing the caller does not already know; the guide's inventory of anonymous reads must still name it.
A blank line between the two rows split the table, so the export row would have rendered as loose text.
remyluslosius
added a commit
that referenced
this pull request
Sep 22, 2026
The audit section keeps one export table row (both sides carried the same joined row) and takes this branch's export paragraph, which describes the implemented behavior, over #870's temporary limitation paragraph.
remyluslosius
added a commit
that referenced
this pull request
Sep 27, 2026
… guidance CHANGELOG [Unreleased] gains the ten PRs merged after v0.8.0-rc.5 (#870 to #879; #874 is CI-only and is not listed). Upgrade notes lead: the 0065 migration signs everyone out, cookie logout requires the CSRF token, and the audit export refuses an unknown parameter. Each entry was checked against the merged code: the 0065 migration body, the binder's sid check and EvaluateBearerBinding, the logout CSRF branch, the LockWaitBound, OperationDeadline and RollbackCleanupLimit constants, and the auth.login.failure and admin.user.enabled declarations in audit/events.yaml. Known limitations name CP bugs/OW-072 and OW-062. QUICKSTART's incident step said active sessions end "via logout" and told operators to rotate passwords. Logout ends one login, and a user's own password change signs out nothing else (OW-072). It now names disable and the administrator reset, which end every interactive credential since #875 and #876. SECURITY_INCIDENT said an access token is ended only by rotating the signing key. Since #876 it names its session and is refused once that session is revoked, so revoking the rows ends it with no restart. Key rotation is kept, scoped to a key that may itself be exposed.
remyluslosius
added a commit
that referenced
this pull request
Sep 27, 2026
… guidance (#883) * docs(release): record the changes since rc.5 and correct the incident guidance CHANGELOG [Unreleased] gains the ten PRs merged after v0.8.0-rc.5 (#870 to #879; #874 is CI-only and is not listed). Upgrade notes lead: the 0065 migration signs everyone out, cookie logout requires the CSRF token, and the audit export refuses an unknown parameter. Each entry was checked against the merged code: the 0065 migration body, the binder's sid check and EvaluateBearerBinding, the logout CSRF branch, the LockWaitBound, OperationDeadline and RollbackCleanupLimit constants, and the auth.login.failure and admin.user.enabled declarations in audit/events.yaml. Known limitations name CP bugs/OW-072 and OW-062. QUICKSTART's incident step said active sessions end "via logout" and told operators to rotate passwords. Logout ends one login, and a user's own password change signs out nothing else (OW-072). It now names disable and the administrator reset, which end every interactive credential since #875 and #876. SECURITY_INCIDENT said an access token is ended only by rotating the signing key. Since #876 it names its session and is refused once that session is revoked, so revoking the rows ends it with no restart. Key rotation is kept, scoped to a key that may itself be exposed. * docs(runbook): disable a compromised account instead of deleting it Three defects in SECURITY_INCIDENT, all present in v0.8.0-rc.5 (CP bugs/OW-082), kept in their own commit so they can be dropped independently. - "There is no is_active flag; disabling an account means soft-deleting it." POST /api/v1/users/{id}:disable has existed since #601 and, since #875, ends every interactive credential. The section now leads with disable, which :enable reverses, and keeps delete and the SQL fallback with what each does and does not do. - The delete was said to be audited as account.user.deleted, which is the host-side /etc/passwd event. DeleteUserByID emits admin.user.deleted. - Recovery verification step 3, headed "No live sessions for disabled accounts", checked only deleted_at. It now checks disabled_at too.
remyluslosius
added a commit
that referenced
this pull request
Sep 28, 2026
Stage 1 for the sixth 0.8.0 candidate, from main fc1117d. VERSION is 0.8.0-rc.6 in packaging/version.env, the README phrase and the newest CHANGELOG heading; CODENAME stays Eyrie. The hygiene test binds the three. The changelog section records rc.5 on facts: built, every machine gate passed, assets published as a pre-release, no human verdict recorded for its fleet checks, documentation review or release-captain signature, tag and assets preserved. Since rc.5: #870 to #881, #883 and #882. The [Unreleased] notes move into the rc.6 section unchanged. Known limitations gain the two the readiness record lists as shipping with v0.8: drift does not distinguish a corpus change from a host change (D-2 S-3, accepted 2026-09-26), and scan variable values are not type checked (OW-080). Next unused candidate number verified: no v0.8.0-rc.6 tag on the remote or locally, and no release or draft of that name. No tag, publication or attestation.
remyluslosius
added a commit
that referenced
this pull request
Sep 28, 2026
Stage 1 for the sixth 0.8.0 candidate, from main fc1117d. VERSION is 0.8.0-rc.6 in packaging/version.env, the README phrase and the newest CHANGELOG heading; CODENAME stays Eyrie. The hygiene test binds the three. The changelog section records rc.5 on facts: built, every machine gate passed, assets published as a pre-release, no human verdict recorded for its fleet checks, documentation review or release-captain signature, tag and assets preserved. Since rc.5: #870 to #881, #883 and #882. The [Unreleased] notes move into the rc.6 section unchanged. Known limitations gain the two the readiness record lists as shipping with v0.8: drift does not distinguish a corpus change from a host change (D-2 S-3, accepted 2026-09-26), and scan variable values are not type checked (OW-080). Next unused candidate number verified: no v0.8.0-rc.6 tag on the remote or locally, and no release or draft of that name. No tag, publication or attestation.
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
CP
bugs/OW-065. Eight factual corrections todocs/guides/API_GUIDE.md, each checked against the contract, the code or an annotated test. None changes a product promise; where behavior is unresolved, the guide says so and names the request, and nothing is presented as fixed.api-sso;licensePublicFieldsscope_idrequired for host scope, forbidden for systemcredential.validate,api-credentialsAC-03, migration 0007 CHECKnext_cursorbecomescursor; hosts unpaginatedapi/openapi.yamlpage schemasinternal/config/load.goenvOverrides(10 variables)correlation_idand unknown-parameter gaps namedaudit_export_handler.go;bugs/OW-064server.go,spa.go, codegen default handler;bugs/OW-063expires_at; CSRF sentencesystem-api-tokens;system-http-serverCSRF constraintPostAuthLogout;bugs/OW-062Documentation only (one file plus the detect-secrets baseline's line-number refresh). The contract's
scope_iddescription is deliberately not here: it regenerates code, which belongs with the OW-011 contract PR under annotated tests.Ordering
Merge before the OW-063 and OW-064 PRs; each of those revises the sentence that names it.
Candidate impact
v0.8.0-rc.5is immutable; its guide is at blob51dacddfand this PR changes nothing there.Checks
check-doc-style.pyclean; pre-commit full-tree doc style passed;TestDocs_NoBrokenRelativeLinks, doc-style-gate and documentation-review-gate tests pass.