Let the API create a token that carries a vault - #839
Merged
blaipr merged 1 commit intoAug 23, 2026
Merged
Conversation
POST /api/v1/auth-tokens answered 500 "Error while retrieving master password from context" for every action a token carries a vault for — the five SECURED_ACTIONS and the three CAN_USE_SECURE_TOKEN_ACTIONS, so ACCOUNT_VIEW and ACCOUNT_CREATE among them — with or without a password, while the web created the same tokens without difficulty. Sealing a vault needs the master password on the context, and the API only loads that from the calling token's own vault, which AUTHTOKEN_CREATE did not have. Fixing it is a decision rather than a repair, which is why it was recorded first: AUTHTOKEN_CREATE and AUTHTOKEN_EDIT are now themselves on CAN_USE_SECURE_TOKEN_ACTIONS, so a token that can mint tokens also carries the master password. That is the authority the web already grants, since an administrator who can reach the tokens page has unlocked the vault with their own password — but on the API it is a bearer credential in somebody's script, so it is worth as much as the vault. Two things follow, both enforced in AuthTokenBase::prepareSecureToken(). The password on such a token is required rather than optional, because without it the vault is sealed with the empty string and nothing can open it: tokenPass is a required parameter and required refuses the empty string. And creating one needs a calling token that already carries a vault, so an AUTHTOKEN_CREATE token minted before this change gets a 401 until it is re-issued; the web can always issue the first one. The tests round-trip rather than only mint: an ACCOUNT_VIEW token created through the API is then used to read an account with customFields, which is the path that needs the vault. All eight vault-carrying actions are covered, a missing password is refused, and an action carrying no vault still needs none. AuthTokenHelp is unchanged: password stays optional there because it is conditional on the action, and ApiHelpMatchesControllersTest pins the declared flag against what the controller reads.
blaipr
deleted the
feat/the-api-can-create-a-token-that-carries-a-vault
branch
August 23, 2026 00:47
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
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.
Closes the gap recorded in
CLAUDE.mdsince #834.The gap
POST /api/v1/auth-tokensanswered 500 "Error while retrieving master password from context"for every action a token carries a vault for — the five
SECURED_ACTIONSand the threeCAN_USE_SECURE_TOKEN_ACTIONS, soACCOUNT_VIEWandACCOUNT_CREATEamong them — with or withouta
password. The help documentsactionIdwith no restriction and the web creates the same tokenswithout difficulty, so this was an oversight, not a policy.
Sealing a vault needs the master password on the context. The API only ever loads that from the
calling token's own vault, and
AUTHTOKEN_CREATEwas on neither list, so it had none.The decision
This was recorded rather than patched because fixing it is a decision, not a repair:
AUTHTOKEN_CREATEandAUTHTOKEN_EDITare now themselves onCAN_USE_SECURE_TOKEN_ACTIONS, so atoken that can mint tokens also carries the master password.
That is the authority the web already grants — an administrator who can reach the tokens page has
unlocked the vault with their own password — but on the API it is a bearer credential living in
somebody's script, so it is worth as much as the vault. Two consequences, both enforced in
AuthTokenBase::prepareSecureToken()and both recorded inCLAUDE.md:is sealed with the empty string and nothing can ever open it, because
tokenPassis a requiredparameter and required refuses the empty string. This is the same rule Ask for a token password whenever a vault will be built #833 gave the web form,
asked at the other door;
AUTHTOKEN_CREATEtokenminted before this change has none and gets a 401 until it is re-issued; the web can always issue
the first one.
Test
In
AuthTokenRoundTripTest, which already round-trips a token rather than only minting one:ACCOUNT_VIEWtoken through the API, then usethe string it answers with to read an account with
customFields— the path that needs thevault. Minting it is only half the claim;
happened to be tried;
Password cannot be blank;"every token needs one".
Mutation-checked: reverting
src/fails exactly those ten and leaves the four pre-existing testspassing.
PHPStan level 6 and PHPCS clean.
AuthTokenHelpis unchanged on purpose:passwordstaysrequired: falsethere because it isconditional on the action, and
ApiHelpMatchesControllersTestpins the declared flag against whatthe controller actually reads.