Data access credentials

A provider HTTP data plane hands the consumer a short-lived access JWT plus a refresh grant instead of a permanent token. Flows shows how an application obtains and uses them; configuration lists the lifetimes and key settings. This page covers what an operator has to get right.

Signing key

The plane signs access tokens and will not start without a key. Supply a private JWK through dataAccess.signingKeyPath or dataAccess.signingKey, with a stable kid and one of ES256, ES384, RS256 or EdDSA. Keep the key and the database across restarts: generating a new key per pod start invalidates every outstanding credential. GET /.well-known/jwks.json publishes only the public keys.

To rotate, supply a new private key with a new kid and keep the old public JWK in dataAccess.previousPublicKeys for at least the maximum refresh-grant lifetime, because a refresh proof may reference an access token signed with the old key. Remove it afterwards.

Replicas

Use one worker replica with persistent state. Refresh rotation uses a database compare-and-swap, but this alone does not establish correctness for multiple replicas. A shared PostgreSQL database and signing key are prerequisites for further replica testing; separate SQLite files cannot coordinate rotations.

Operational notes

Public proxy and refresh endpoints require HTTPS; plain HTTP is for local development only and logs a warning at startup.

A refresh grant is single-use. The provider rotates it and the consumer persists the result in separate transactions, so a consumer crash in between leaves a refresh token the provider has already retired; that transfer has to be started again.

The consumer only renews against the origin that serves the data, and rejects redirects at the refresh endpoint, so a provider cannot direct proof credentials at another host.

Suspension, completion and termination revoke renewal. Resume issues a new generation, and credentials from before the resume stay invalid.

Execution leases

Every flow requires an unexpired execution lease stored with its immutable owner. An access JWT and refresh grant cannot keep a flow alive after that lease expires. The control plane renews leases through POST /dataflows/:id/lease using the same verified ownership as other signaling operations. A status request does not extend execution authority.

The lease ends at the earlier of the verified signaling JWT expiration and the authenticated control plane's X-TSG-Execution-Valid-Until deadline. The latter is the earlier authorization projection expiry of the owner and any exact-DID-matched locally managed counterparty. Prepare, start, resume and renewal reject a missing, invalid or expired deadline. Suspension or deletion of either local participant stops renewal. An external peer's lifecycle remains that peer's authority. The revocation bound depends on projection freshness, token lifetime and synchronized clocks.

New proxy requests and refreshes fail closed once the stored lease expires; already-open streams may finish. An expired flow must be suspended and resumed through authenticated control-plane signaling before it can serve again.

Keep the worker database and signing key across restarts. Legacy workers without verified execution owners have separate histories. Drain their transfers, create tenant-local registrations for the new endpoint, relink dataset registrations and start new transfers. Do not combine databases or assign unowned rows to a guessed tenant. Existing URLs and grants belong to their original worker.