Submit an edge installation's signed monthly usage report
An edge installation counts the governed actions it decided per UTC
month from its hash-chained evidence and reports them as a compact
JWS (EdgeUsageReportHeader, EdgeUsageReportClaims) signed with an
Ed25519 key the organization registered at
/v1/execution/provider-keys with purpose usage_report and the
installation id as its issuer.
Verified like an effect receipt: the header, the key (this
organization's, this purpose only), the signature, iss = the key's
issuer, aud = the organization, iat at most 5 minutes ahead, a
month that has begun, and claims that add up (each breakdown sums to
total, delegated <= total, the chain range present exactly when
something was counted, period_start/period_end the month's
bounds). A refused report is answered 422 with its code and not
stored.
One report per installation and month is current. The same report
again is answered 200 with the stored record (replay: true). A
different report for the same installation and month is accepted
only when it counts further along the same chain stream (a higher
chain.last_seq): it supersedes the current one, which stays on
record pointing at it; otherwise 409.
A stored report adds total - delegated governed actions (minus what
earlier reports for that installation and month already metered) to
the organization's usage through the governed-action meter hosted
decisions use, dated in the reported month when the meter still
accepts it, so plans, allowances and overage apply unchanged.
delegated decisions were decided by hosted Decionis, which metered
them already. Metering is fail-open: the report is recorded either
way, with meter_status.
Requires an organization API key with policy:read, policy:write,
policy:* or org:*: the report's signature, not the API key, is
what is trusted.
Authorization
ApiKeyAuth An organization API key. Its scopes decide what it may call;
decision:shadow is the narrowest: SHADOW evaluations through
POST /v1/authority/grants or its alias
POST /v1/authority/enforce-and-bind only (DECISION_SHADOW_MODE_DENIED
in any other mode; DECISION_SHADOW_FIELD_DENIED for a body carrying
context.decionis_policy, evidence or escalation), with no
integration dispatch. A key whose only scope is decision:shadow
(an AgentSafe hosted gateway's) reaches exactly those two,
POST /v1/auth/credential-context, POST /v1/hosted-gateway/keys/confirm
and POST /v1/hosted-gateway/keys/revoke-self; every other route
answers 403 HOSTED_GATEWAY_KEY_PATH_DENIED.
decision:enforce is an enforced hosted gateway's key: evaluations
in SHADOW or ENFORCEMENT through POST /v1/authority/grants or its
alias (400 DECISION_ENFORCE_FIELD_DENIED for a body carrying
context.decionis_policy; it never holds policy:write), and the
grants and managed escalations they bind. A key whose scopes are
decision:enforce (with or without decision:shadow) reaches exactly
POST /v1/authority/enforce-and-bind, POST /v1/authority/grants,
GET /v1/authority/grants/{grant_id},
POST /v1/authority/grants/{grant_id}/claims,
POST /v1/authority/grants/{grant_id}/receipts,
POST /v1/authority/grants/{grant_id}/reconciliations,
POST /v1/execution/verify-token, POST /v1/execution/claim-token,
POST /v1/execution/consume-token, POST /v1/execution/finalize-token,
GET /v1/authority/escalations/{escalation_id},
DELETE /v1/authority/escalations/{escalation_id},
POST /v1/auth/credential-context, POST /v1/hosted-gateway/keys/confirm
and POST /v1/hosted-gateway/keys/revoke-self, each id a UUID; every
other route answers 403 HOSTED_GATEWAY_KEY_PATH_DENIED.
In: header
Request Body
application/json
The usage report as a compact JWS.
1 <= length <= 524288Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/edge/usage-reports" \ -H "Content-Type: application/json" \ -d '{ "report": "string" }'{ "replay": true, "report": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "installation_id": "string", "kid": "string", "jti": "string", "period": "string", "period_start": "2019-08-24T14:15:22Z", "period_end": "2019-08-24T14:15:22Z", "issued_at": "2019-08-24T14:15:22Z", "counts": { "by_mode": { "ENFORCEMENT": 0, "SHADOW": 0, "PARALLEL": 0 }, "by_verdict": { "ALLOW": 0, "ESCALATE": 0, "BLOCK": 0 }, "total": 0 }, "delegated": 0, "billable": 0, "chain": { "stream": "string", "first_seq": 0, "last_seq": 0, "first_hash": "string", "last_hash": "string" }, "bundles": [ "string" ], "report_digest": "string", "supersedes": "09391fa8-b623-4dc7-8d11-2a46489536bf", "superseded_by": "a99fa58d-1b9b-4688-ad5f-382f6b17ef46", "metered_actions": 0, "meter_status": "pending", "received_at": "2019-08-24T14:15:22Z" }}List the organization's edge usage reports GET
Every usage report recorded for the authenticated organization, newest first, superseded ones included (`superseded_by`), optionally for one month. The report JWS itself is kept as evidence and not returned. Requires an organization API key with `policy:read`, `policy:write`, `policy:*` or `org:*`.
Public keys for signed policy bundles GET
The Ed25519 public keys, as a JWKS, that sign policy bundles for the edge evaluator. An edge evaluator release pins these keys at build time; during a signing-key rotation the previous key stays listed until the bundles signed with it have expired. The `kid` in a signed bundle's protected header names the key to use.