Skip to main content
GET
Report authorization denials by surface for your organization
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Counts the decisions recorded for your organization that a permission check blocked, by the surface the dispatch came from. Each row’s key is a recorded dispatch surface. A permission denial with no surface recorded is counted in unknownCount.

Who can read it

Your credential must act within an organization, and its role grants must hold grants:read, policies:read and audit:read at that organization when the request runs. A credential with no acting organization returns 403. The report counts only decisions recorded for exactly your acting organization with no private fence: other organizations’, personal, platform-wide, private-chat and client-reported decisions are never counted, and no row names a person.

Parameters

Any other parameter — an organization, a person, a view — returns 400, as does a repeated one.

Coverage

Reports cover your organization’s recorded decisions; check coverage.status before treating counts as complete.
  • complete: the whole window was read.
  • partial with reason window_cap: the window held more decisions than windowCap. The cap counts every organization’s decisions in the window, so on a busy deployment narrow the window until coverage is complete. sampled is true.
  • partial with reason resolution_read_budget: the read ran out of evidence resolution reads. sampled is true.
  • unavailable with reason unresolved_attribution: a decision in the window has an unknown audience and might be your organization’s, so the counts are not proof of the window.
  • unavailable with reason source_unavailable: the decisions could not be read; rows is empty.
coverage.examined and coverage.eligible count only your organization’s decisions. resolutionRevision names the evidence resolution state the report was read at.

Example

Over MCP, forge_call_operation with operationId getAuthzSurfaceReport returns the same data and meta as its body.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

startAt
integer
required

Window start, epoch milliseconds.

Required range: x >= 0
endAt
integer
required

Window end, epoch milliseconds; after startAt and at most 30 days after it.

Required range: x >= 0
windowCap
integer
default:2000

Most decisions read from the window, counted across every organization before your organization's are selected.

Required range: 1 <= x <= 2000

Response

The report

data
object
required

Reports cover your organization's recorded decisions; check coverage.status before treating counts as complete. The window cap counts every organization's decisions in the window, so on a busy deployment narrow the window until coverage is complete. One report over the window window.since..window.until (epoch milliseconds). Each row's key is a failed gate id (gate_denials), a trust policy id (policies_fired), a recorded dispatch surface (authz_denials_by_surface) or a recorded person id (denials_by_person); unknownCount counts decisions that matched the report but recorded no key. sampled is true when the window cap or the resolution read budget stopped the read. passTallies is present only when getGateDenyReport is asked with includePassTallies=true.

meta
object
required