List the organization's edge usage reports
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:*.
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
Query Parameters
1 <= value <= 20050^2[0-9]{3}-(0[1-9]|1[0-2])$Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/edge/usage-reports"{ "reports": [ { "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" } ]}The organization's signed edge-evaluator entitlement GET
A compact JWS stating what the authenticated organization is licensed for: its plan, deployment tier (`hosted` | `dedicated` | `self_managed`), included governed actions per month, volume band (self-managed only), whether the edge evaluator is included (`edge`), and how many days after a month ends its usage report is due. Valid 35 days. Issued to every organization, entitled or not: an edge installation verifies it against the policy-bundle JWKS (`/.well-known/decionis-policy-bundle-jwks.json`; same key, its own `typ`) and uses it only to warn — a licence problem never stops or degrades a decision. Requires an organization API key with `policy:read` (or `policy:*` / `org:*`).
Submit an edge installation's signed monthly usage report POST
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.