Security and data protection

Vision uses short-lived, narrowly scoped machine identity and keeps App business authority at the resource server. Integrators remain responsible for secure credential custody, least privilege, and appropriate handling of returned data.

Trust model

Vision Core issues machine credentials and applies common token policy.
Each App has its own audience and workspace semantics.
Resource servers validate the token and independently authorize every operation.
App entitlement proves only that the client may address the App; scope and record permission still apply.
Public projections are explicit copies of allowlisted fields, not live views over private tables.
Documentation publication does not provision a client or make a restricted runtime public.

A bearer token is authority in the hands of its holder. TLS, origin validation, audience validation, short lifetime, and secret-safe observability are all required; none compensates for another being absent.

Credential handling

Store client secrets only in a server-side secret manager or equivalently controlled runtime configuration.
Never embed credentials in browser JavaScript, mobile binaries, desktop bundles, repositories, images, support tickets, analytics, or logs.
Restrict secret access to the process and operators that need it.
Displayed client and webhook secrets are one-time values. Loss requires rotation, not recovery.
Rotate deliberately and revoke immediately after suspected exposure.
Use separate clients and credentials for separate environments and trust purposes.
Do not share a credential among unrelated services merely to reduce administration.
Keep access tokens in server memory and refresh shortly before expiry; do not persist them as durable session state.

Vision stores client secrets as memory-hard verifiers rather than recoverable plaintext. That protects the server-side store; it does not make a leaked client copy harmless.

Token validation

A resource server must validate all of the following before applying App authorization:

Name
signature
Description
Verify with a currently trusted public key and an explicitly allowed algorithm.
Name
issuer
Description
Pin the configured Vision issuer; do not accept a token-controlled issuer.
Name
audience
Description
Require the exact resource-server audience.
Name
exp, iat
Description
Reject expired tokens and unreasonable time claims within the accepted clock-skew policy.
Name
credential_version
Description
Accept only the supported Vision service-credential vocabulary.
Name
vision_org_id
Description
Bind the token to the expected Vision organization.
Name
app_workspace_ref
Description
Bind every query and command to the App workspace.
Name
app_entitlements
Description
Require the target App.
Name
scope
Description
Require every operation scope declared by the route.
Name
identity_class
Description
Enforce whether the operation permits a service, worker, agent, or human context.

Fetch verification keys only from the configured Vision JWKS endpoint. Never follow a key URL supplied inside an untrusted token. Unknown key IDs should trigger controlled key refresh and then fail closed.

Data protection

Request the minimum fields and scopes needed for the workflow.
Keep workspace boundaries in every storage key, queue message, cache entry, and job.
Preserve opaque public references; do not attempt to derive internal IDs.
Treat CRM contact, consent, commercial, task, and relationship data as private unless an explicit projection says otherwise.
Treat Calendar event details, attendees, availability, and working patterns as private. Availability endpoints deliberately avoid returning event detail.
Treat Accounting counterparties, invoices, imports, provider metadata, and financial records as restricted financial information.
Honor suppression, retention, withdrawal, and record-visibility decisions made by the owning App.
Encrypt protected data in transit and at rest according to your own risk and retention obligations.
Do not copy complete API payloads into lower-trust analytics or troubleshooting systems.

Logging and support

Safe operational evidence usually includes:

request or correlation ID;
operation ID or method/path;
contract version;
response status and stable error code;
attempt number and bounded latency;
safe client and App references where policy permits;
timestamp and environment.

Do not log:

authorization headers or bearer tokens;
client or webhook secrets;
OAuth codes, private keys, or cookies;
complete request/response bodies containing private data;
raw webhook signature material beyond what is strictly required for safe diagnostics.

When requesting support, provide the safe identifier and timestamp rather than a credential or full payload.

Webhook egress

Vision webhook registration and delivery reject loopback, private, link-local, reserved, and metadata-service destinations. Endpoints must use approved HTTPS hosts. Delivery re-resolves and rechecks the destination rather than trusting registration-time DNS forever.

Receivers must verify the exact raw bytes, timestamp, signature length, and HMAC in constant time before parsing. Reject stale or replayed event IDs, persist acceptance before returning 2xx, and return success only after durable handling.

See webhooks for the signature and retry model.

Production checklist

A public security-reporting address and stable production support policy are release requirements but are not yet published in the preview contract.