Permissions and network access

A document has no network access unless it declares a capability and the user grants it.

Declaring a capability

"requiredCapabilities": [{
  "id": "ai",
  "type": "network",
  "origins": ["https://api.example.com"],
  "methods": ["POST"],
  "credentialBinding": "api-key",
  "purpose": "Generate answers"
}]

• origins: one to sixteen exact HTTPS origins, with no path.
• methods: a subset of GET, POST, PUT, PATCH, DELETE.
• purpose: up to 240 characters, shown to the user.

Use optionalCapabilities for access the document can work without; the user may decline it and the document still runs.

Credentials

"credentialBindings": [{ "id": "api-key", "required": true, "description": "Key for api.example.com" }]

A binding names no service and contains no secret. The user stores the actual key in the reader and chooses which origins it may be sent to. The reader attaches it only after every check passes — and the document never sees it.

Environment bindings

"environmentBindings": [{ "id": "region", "variable": "API_REGION", "required": false }]

Non-secret configuration, returned by idop.env.get('region'). Never use environment bindings for secrets: their values are readable by the document.

Consent

Before the document runs, the reader shows each capability: which credential would travel to which origins, for what purpose. The user can cancel, allow once, or allow for this version. “This version” means this application id and version, this exact code and these exact capability declarations — changing any of them asks again.

What the reader enforces on every request

• the capability was granted, the origin is exactly declared, the method is listed;
• authorisation and cookie headers supplied by the document are removed;
• redirects are not followed;
• request size, response size, time and concurrency are bounded;
• each session has a finite request budget (IDOP-NETWORK-BUDGET-EXHAUSTED).

A non-2xx response from the service is not an error: it is returned with its status.