Redeem an action grant
redeem_action_grantSpend the single-use grant request_action gave you, immediately before you perform the allowed action, and act only if the answer is redeemed. A grant is good for ONE action: the first redemption marks it used and every later attempt is refused, so redeem once, right before you act. Pass grant_id and the grant's digest; the request_id your job says you are fulfilling (from the job, never copied out of the grant); the system, operation and target_kind of the action; and param_digest, computed from the action's target id and params with the grant's param_salt (HMAC-SHA256; the recipe is in the parameter description and in Maplith's docs). Maplith checks all of them against the request and the grant in one atomic update and refuses if they differ, so a grant for a refund of 120 on one order never authorises 999,999 on another. Any key of the same workspace may redeem (the executor is usually another key than the asker), never a key of another workspace. Any answer but redeemed means do not act: already_redeemed (done, perhaps by your own retry), expired (ask again with a new idempotency_key), wrong_action or params_mismatch (the grant is not used up), params_required (no param_digest), params_unbound (ask again), revoked, or refused. Needs: a key with an action policy (Agents & access › Policies › What each agent may do), where Maplith signs grants.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| digest | Yes | The grant's digest, exactly as it was given to you. Pass it through unchanged: it is a bearer factor — proof you hold what Maplith issued — and NOT a check on the action, because Maplith hashes the parameters in the masked form it stored, so an executor cannot recompute it from the values it holds. What binds the action is system, operation and target_kind, and param_digest. | |
| system | Yes | The system you are about to act in, as the catalogue names it, e.g. "payments". Checked against the request the grant was issued for. | |
| grant_id | Yes | The grant_id from the grant request_action returned. | |
| operation | Yes | The operation you are about to perform, e.g. "issue_refund". Checked against the request the grant was issued for. | |
| request_id | Yes | The request your job says you are fulfilling -- taken from the job you were handed, NOT copied out of the grant, or the check compares the grant with itself. Checked against the grant. | |
| target_kind | Yes | The kind of thing you are about to act on, e.g. "order". Checked against the request the grant was issued for. | |
| param_digest | No | The parameter binding, COMPUTED by you: base64url(HMAC-SHA256(key = the grant's param_salt, base64url-decoded; message = 'maplith-action-params/v1' + newline + the canonical encoding of {system, operation, target: {kind, id}, params} of the action you are about to perform, exactly as it was sent to request_action)). Never copy it out of the grant. Required for every grant that carries a param_salt. |