Register a data source

Before you start

You need an administration credential, the system your input lives in, and a secret that already sits in your credential store. A work key cannot register a source.

You also need to know which workflow will read it. A source is registered once and used by many runs, so register the narrowest access that workflow needs.

Choose an adapter with published evidence

Each adapter declares one compatibility level: import_compatible, wire_subset_compatible, official_sdk_compatible or full_endpoint_compatible.

A level on its own means nothing. Each is backed by a versioned conformance matrix stating the supported upstream version, fields, lifecycle, errors and limits.

Read that matrix before you commit to an adapter. A claim that something is compatible, without a named level and a published matrix, is not evidence you can plan against.

Register a reference, never a secret

Your request carries a credential_ref. That is a pointer to a secret your account already holds, not the secret itself.

Never put a literal secret in a request, a configuration file or a command line. Credentials are stripped before manifest, job and delivery records are persisted, so a leaked value has no place to be recovered from anyway.

If you do not have a stored secret yet, store it first, then register the source against its reference.

Test the access narrowly

The source family has a test operation. Use it before any workflow depends on the source.

Test with the smallest read you can: one object, one table, one prefix. A test that reads everything proves that a wide grant works, which is not what you wanted to know.

If the test refuses, read the reason and the next action together. A refused test is cheaper than an admitted job that fails on its first read.

Confirm the snapshot is immutable

Work is never pinned to a live source. Before a run begins, the input is snapshotted, and the snapshot carries a version_id and a content_sha256.

That pair is the contract. If the underlying data changes afterwards, your run is unaffected, and a later run against the same snapshot reads exactly the same bytes.

Check both values on your quote and again on the result's provenance record. If they match, you know which bytes produced which result. See how immutable snapshots are pinned when the two do not agree.

Confirm success

The source reads back as VERIFIED, and its test operation passes on a small read. A quote that names the source reports the snapshot you expected.

Keep the receipt reference the apply returned. It is what you quote to support if access behaves differently later.

Revoke access safely

Revoking is a forward act, not an undo. Revoke the source, then read it back, then check its events.

Do this in that order. A revoke response tells you the request was accepted; only the read-back tells you the current state. Running work that already holds a snapshot is unaffected, because it no longer needs the source.

If a revoke refuses, it names why and what to do next. A CONFLICT means the source moved since your plan, so inspect it and plan again.

Register a destination for results