---
title: "Revalidate and atomically claim a grant once, immediately before commit"
method: POST
path: "/v1/authority/grants/{grantId}/claims"
---

# Revalidate and atomically claim a grant once, immediately before commit

`POST /v1/authority/grants/{grantId}/claims`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/authority/grants/{grantId}/claims`
- Auth: HTTP bearer

The handler of the deprecated aliases `POST /v1/execution/claim-token`
and `POST /v1/execution/consume-token`, with the same body and the same
responses: execution is authorized only when `should_execute` is
`true`, `claim_token` is non-null and `claim_lease_expires_at` is still
live at the downstream boundary, and a live claim returns
`claim_attestation`. The verified token's `jti` must be `{grantId}`;
otherwise the answer is 409 `GRANT_ID_MISMATCH` and nothing is claimed.

## Request body

- ExecutionClaimTokenRequest
  - `execution_token` string, required
  - `intent_hash` string, required
  - `intent` ExecutionIntentBinding, required
    - `protocol_version` 'agent-safe.intent/1', required
    - `tenant_id` string, uuid, required
    - `intent_id` string, uuid, required
    - `captured_at` string, date-time, required
    - `expires_at` string, date-time, required: Must be later than captured_at and no more than five minutes after it.
    - `actor` ExecutionIntentActor, required
      - `id` string, required
      - `type` string, required
      - `runtime` string
      - `trust_level` string
    - `action` ExecutionIntentAction, required
      - `type` string, required
      - `resource` string, required
      - `parameters` object, required
    - `context` object, required: The trusted runtime's context, entirely inside the canonical intent hash. Open by design, with three reserved keys. `idempotency_key` is required and carries the retry identity. `enforcement_boundary` and `workload` are what an enforcement boundary reports about itself and about the software that proposed the action; each is validated against its schema when present, and an absent signal is an answer rather than a placeholder, so a policy that requires provenance refuses on its absence. `runtime_attribution` is reserved for Decionis, which computes it from those reports, and a request that supplies it is refused.
      - `enforcement_boundary` EnforcementBoundarySignal: Which enforcement boundary admitted the intent. The identity is of the configured logical boundary, not of the process running it: a restart, a rescheduling or a scale-out leaves it unchanged, and the container, pod and node are deliberately absent, so an effect's evidence names the door rather than whichever instance was alive at the time.
        - `boundary_id` string, required: What the operator calls this boundary, or a stable id derived from its configuration.
        - `agentsafe_version` string, required
        - `protocol_version` 'agent-safe.intent/1', required
        - `deployment_type` string, required: What the boundary was installed as, for example docker, kubernetes or linux.
        - `environment` string
        - `conformance_version` string
        - `placement` object: Stable placement only. It survives a restart and is what a policy means by an environment and a region.
          - `cluster_id` string
          - `namespace` string
          - `region` string
          - `workload_id` string
      - `workload` WorkloadSignal: What software proposed the action, as a runtime reported it. Decionis records the report and does not establish it: image digests, provenance attestations and publisher verification belong to the container and OCI tooling that produced them. Every field is optional but `provenance`, because a workload cannot be expressed without saying who reported it and how far that report goes.
        - `runtime` string
        - `artifact_type` string
        - `image` string
        - `digest` string
        - `publisher` string
        - `provenance` object, required
          - `source` string, required: Who reported it, for example docker, kubernetes or operator.
          - `trust_level` 'unverified' | 'supplied' | 'observed' | 'verified', required: How far the producer said its report goes. It is the producer's claim, recorded as such: Decionis neither raises nor lowers it. A policy that means the platform checked something matches on the decision's `runtime_attribution.platform_verified` instead, which Decionis computes and a caller cannot assert.
    - `downstream_target` ExecutionDownstreamTarget, required
      - `system` string, required
      - `operation` string, required
      - `environment` string
      - `endpoint` string
    - `policy_projection` ExecutionPolicyProjection: Exact policy-routing vocabulary committed into the intent. Protocol adapters use it when their evaluated decision type differs from the executable action type; legacy generic callers may omit it.
      - `decision_type` string, required
      - `transaction_type` string, nullable, required
      - `workflow_key` string, nullable, required
      - `channel` string, nullable, required
    - `expected_effect_digest` string: Digest-only commitment to the expected downstream state.
  - `consumed_by` string
  - `commit_correlation_id` string
  - `claim_lease_seconds` integer: Pre-commit lease duration. This does not extend the signed execution grant lifetime.

## Response `200`

Authorization remains valid and the nonce is claimed

- ExecutionClaimTokenResponse: Successful pre-commit claim response. All three execution-bound fields are required; `valid` alone never authorizes execution.
  - `valid` boolean, required
  - `should_execute` true, required: Present on pre-commit claim responses. Only true after current-state and Presence revalidation, an atomic nonce claim with durable evidence, and a final database-time claim-lease check.
  - `would_block` boolean: Present on pre-commit claim responses for Shadow diagnostics.
  - `verdict` 'APPROVE' | 'ESCALATE' | 'REJECT' | 'REVIEW': Deterministic pre-commit revalidation verdict.
  - `reason_codes` string[], required
  - `claims` ExecutionTokenClaims, required
    - `iss` string, required
    - `sub` string
    - `aud` string
    - `org_id` string, uuid, required
    - `dossier_id` string, required
    - `decision_id` string, required
    - `chain_id` string
    - `action` string, required
    - `decision` 'allow', required
    - `scope` 'execute', required
    - `binding` object, required
      - `intent_hash` string, required
      - `execution_binding_digest` string
      - `execution_payload_digest` string: Signed digest of the exact downstream request parameters.
      - `execution_payload_canonicalization_profile` string: Canonicalization profile used for execution_payload_digest.
      - `execution_nonce` string
      - `execution_correlation_id` string
      - `expected_effect_digest` string: Expected downstream effect commitment carried by the grant.
      - `authority_protocol_version` '1.0' | '1.0.0' | '1.1': Protocol semantics governing execution eligibility and effect evidence validation for this grant. Protocol 1.1 grants reject the deprecated legacy effect-evidence shape.
    - `jti` string, required
    - `iat` integer, required
    - `nbf` integer, required
    - `exp` integer, required
  - `claim_token` string, nullable, required
  - `claim_validated_at` string, date-time, nullable, required: Database time of the final execution-eligibility confirmation. Qualifying effect observations must not predate this boundary.
  - `claim_lease_expires_at` string, date-time, nullable, required
  - `claim_attestation` string, nullable, required: Compact EdDSA JWS over `ClaimAttestationClaims`.
  - `evidence` object
  - `evidence_durably_queued` boolean: True when the canonical revalidation evidence is durably queued in the same transaction as the nonce transition. This does not by itself mean the Protocol Decision Chain append has completed.
  - `decision_chain_evidence_recorded` boolean: True when the queued evidence has already been acknowledged by the Protocol Decision Chain. False evidence remains recoverable when evidence_durably_queued is true.

## Other responses

- `400`: Structured API error
- `401`: Structured API error
- `403`: Structured API error
- `409`: Structured fail-closed revalidation outcome, including GRANT_ID_MISMATCH
- `429`: Structured API error
- `503`: Current state cannot be resolved

---

[API](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api.md) · [All operations](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api/revisions/357f5e459d0c?raw)