Capabilities

What a key may do, and how the organization, application and key combine.

On this page

How the layers combine
Every capability
What each request needs
Server-only capabilities
Changing capabilities

A capability is both a product switch and an API scope. Each request is allowed or refused by the capabilities in force for it, worked out again on every request.

How the layers combine#

Three layers each hold a set of capabilities, each a subset of the one above:

The organization: what ReceViz granted it.
The application: what the organization lets this integration use.
The key: what this key may call.

What a request may do is the intersection of all three, and, for a client token, of the token's own list as well. Taking a capability from the organization therefore takes it from every application and every key at once, with nothing to re-issue. A request that needs a capability outside the intersection is refused with 403 missing_capability, and details.missing names it:

json

{
  "error": {
    "type": "permission_error",
    "code": "missing_capability",
    "message": "VERIFIED mode needs the documents.verify capability.",
    "details": {
      "missing": [
        "documents.verify"
      ]
    },
    "request_id": "rv_req_8fK2aQ0zT3mN1pL5vB7xY9",
    "doc_url": "https://receviz.theaccounthouse.com/docs/errors#missing_capability"
  }
}

GET /v1/me returns the intersection for the calling credential as scopes.

Every capability#

Capabilities
Capability	What it allows	Client tokens and publishable keys	In a new organization
`documents.upload`	Send images and PDFs to ReceViz.	May hold it	Granted
`documents.extract`	Run extractions and read their results.	May hold it	Granted
`documents.verify`	Use VERIFIED processing: a language model re-reads the fields that are uncertain.	May hold it	Opt-in
`camera.capture`	Capture documents with the ReceViz SDK camera.	May hold it	Granted
`camera.live_detection`	On-device document detection, quality guidance and auto-capture in the SDKs.	May hold it	Opt-in
`adaptive_tiling`	Read tall or very high-resolution documents in overlapping regions so small print survives.	May hold it	Granted
`ocr.basic`	Return the recognised text of a document.	May hold it	Granted
`ocr.structured`	Return OCR lines with positions and confidence (layout).	May hold it	Opt-in
`schemas.read`	List document types and read their schemas.	May hold it	Granted
`schemas.write`	Create document types through the API.	Never: secret keys only	Opt-in
`schemas.execute`	Extract with your own document types, not only those created from the built-in templates.	May hold it	Granted
`webhooks.receive`	Receive signed webhook events for this application.	Never: secret keys only	Granted
`quality.telemetry`	Report how on-device readings compared with ReceViz's, to measure accuracy.	May hold it	Granted
`usage.read`	Read usage figures through the API.	Never: secret keys only	Granted
`client_tokens.create`	Mint short-lived client tokens for mobile and web apps.	Never: secret keys only	Granted

The opt-in capabilities are the ones with a cost or a wider reach: verification by a language model, structured OCR output, managing document types through the API, and live detection.

Capture capabilities

camera.capture and camera.live_detection describe what an application is set up to use in the capture SDKs. No API request checks them today.

What each request needs#

Capabilities needed per request
Request	Needs
`GET /v1/me`	Any credential but a publishable key
`POST /v1/extractions`	`documents.extract`, and `documents.upload` when a file is sent (text read on the device, `client_ocr`, needs only the first)
`mode=verified`	`documents.verify`, and a data policy that allows language models
Your own document type	`schemas.execute`. Types created from a built-in template do not need it.
`options.tiling=force`	`adaptive_tiling`. Without the capability, tiling is off for the request.
`options.include_ocr=text`	`ocr.basic`
`options.include_ocr=lines`	`ocr.structured`
`GET /v1/extractions`, `GET /v1/extractions/{extraction_id}`	`documents.extract`
`GET /v1/document-types` and the other schema reads	`schemas.read`. Without `schemas.execute`, only types created from a template are listed.
`POST /v1/document-types`	`schemas.write` and a secret key; a custom `definition` also needs `schemas.execute`
`GET /v1/usage`	`usage.read`
`POST /v1/client-tokens`	`client_tokens.create` and a secret key
`POST /v1/client-sessions`	A publishable key
`POST /v1/quality/feedback`	`quality.telemetry`
Webhooks	`webhooks.receive` on the application and its organization. Webhooks belong to the application, so the key that sent the document does not matter.

Server-only capabilities#

Four capabilities manage the integration itself: schemas.write, webhooks.receive, usage.read and client_tokens.create. A publishable key cannot be given one, and a client token never carries one, whatever the key that minted it holds. Everything else may reach an app or a page, through a client token.

See client tokens for how a token's capabilities are chosen.

Changing capabilities#

Your organization's capabilities are granted by ReceViz. You choose the ones you want when you request access.
An application's capabilities are chosen in the console, from the organization's. A key's are chosen from the application's when it is created, and can be changed later.
Asking a key or an application for a capability the layer above does not have is refused with 403 scope_not_granted.