Registration

The credential is asymmetric, and that is the whole design

The management client signs each call with an Ed25519 private key. You register the matching public key.

Nothing secret of yours ever reaches anyone, and nothing they hold is worth stealing from you. Every other property on this page follows from that one.

Three alternatives, and why each was rejected

Not a shared HMAC secret. Simpler, and strictly weaker: their breach becomes your breach. A per-customer HMAC secret means a compromise on their side yields keys replayable against every customer’s production Worker until each of them rotates. Under asymmetric, a full compromise leaks private keys that are useless the moment you revoke the public one — and revoking is a row you delete.

Not OAuth. OAuth exists so a third party can act on behalf of an end user without seeing their credentials. There is no user delegation on this leg — it is their server talking to your Worker — and turning every adopter’s Worker into an OAuth provider is a large surface for a property nobody needs. The one grant that would fit is a shared secret with extra ceremony.

Not Cloudflare Access service tokens or mTLS. Both work, and both move the authorization decision out of your Worker into Cloudflare’s edge configuration. That requires you to run Zero Trust, and it breaks the sentence this design exists to keep true: your Worker is the authority.

One keypair per connection

Per customer, per project, per environment. A leak exposes one connection rather than a fleet, and rotation and revocation are naturally scoped.

The keypair is generated by the management client, and the private half never leaves their infrastructure. The alternative — your CLI generating one and sending it over — puts key material on the wire for no benefit.

The flow

pithy dashboard connect --env prod

Every step below is pithy dashboard connect doing its work.

  1. A device-code flow against the management client’s origin — a short user code, and your browser opens. The same shape as wrangler login. This leg is genuine user delegation, which is why a browser flow belongs here and not on the machine-to-machine one.
  2. You approve. The CLI polls and receives a short-lived connect token.
  3. The CLI requests a connection for this project, this environment, the scopes you chose, and the seam’s address on this Worker.
  4. The client generates the keypair, keeps the private half, and returns the connection id, key id, public key and issuer.
  5. The CLI writes the registration into your D1. This is the one key the CLI ever writes.
  6. Nothing reports connected until a signed ping round-trip succeeds against your Worker.

Who authorized it, what kind of client, and what for

A connection is a standing credential, so it names a person. Before step 1, connect reads who you are from your pithy cloudflare connect session — the email GET /user names under it — and records it as the connection’s authorizing principal. Nobody types it, and no flag supplies it. An account token, a session with no email, or no credential at all is refused before anything is written, in every environment, dev included. An account token deploys; it registers nothing.

The device-code approval cannot be the source. It happens at the management client, and nothing about it comes back: the connect token carries a bearer and an expiry, the issued connection carries the ids, the public key, the issuer and the scopes, and neither carries identity. An account-owned token names only itself, and a token name cannot leave an organization. Only a signed-in session names a person.

Two more facts sit beside it on your row. The kind — dashboard on the device-code path, always, or agent or script, said with --kind when you register a key or an OIDC trust yourself. And the purpose, in your words, one line of plain text, at most 200 characters, with every control character, line break and bidi override refused. Your Worker stamps the connection’s kind onto every control-plane audit row its calls write, so a row says which of the three acted.

connect --update --purpose edits the purpose and records controlplane/connection_updated with the old value and the new. A connection registered before these were recorded keeps working; its principal is set only by registering again, under a session.

The address is resolved, not passed

connect reads it from the project: the Worker’s domains declaration for that environment, else its first route pattern, else a hand-set base URL. It prints what it found and where it came from before registering.

--worker-url overrides — a proxy in front of your Worker has an address no config knows, and that flag is the only way to say so.

It also names the Worker. The administrative surface is composed on one Worker per project. In a project with several, connect refuses the ambiguity and asks for --worker <name> rather than guessing; a Worker composing no control plane is refused outright, because there is nothing to connect to.

The address changes. A custom domain, a renamed Worker, a moved environment — connect --update re-points both the URL and the base path. A connection whose ping fails surfaces as needs reconnecting, never as a silent dead link.

One connection per project and environment

A customer may register several projects, each with its own connection and keypair.

Sibling Workers are not separately addressable, and that is deliberate. The data being administered is shared through binding names by default, so a second connection to a sibling would be a second credential onto the same rows. A sibling that owns its DB through ownBindings is the exception: the connection reaches one app database per environment, so it does not cover that Worker’s own.

Rotation: append, prove, then expire

Rotating and revoking is the operator’s side of what follows.

Never replace. The order is the entire safety property.

  1. Append. Register the new public key, signed with the current one. Your Worker verifies with the key it already trusts and appends. Trust flows forward from existing trust. Both keys are now valid.
  2. Prove. A real call — ping — signed with the new key, confirmed to succeed.
  3. Expire. Only then is the old key given an end date, naming the proven successor — and that call must itself be signed with the successor. Naming a live key is not proof you can sign with it; only signing with it is.

Reverse those, or swap without proving, and a bad rotation locks the client out permanently with no authenticated path back.

Two live keys is a normal state, not an exception.

Registration and expiry are separate calls on purpose. Folding them into one would make append-and-expire atomic — and atomic is precisely wrong here: the point is that the old key survives until the new one is proven.

The Worker refuses an expiry naming an unproven successor, and refuses one that would leave the connection with no live key at all. Lockout is the one failure mode with no recovery path.

Your infrastructure stays passive. Storing a new key is one write in a route handler. No Workflow, no cron on your side.

Rotation is a scope. A client never granted it cannot rotate, whatever it intends — better than a toggle somebody has to be trusted to honor.

Revocation is immediate and unilateral

Delete the registration, or pithy dashboard disconnect --env <environment>.

Requiring nothing from anyone else. That is the property that makes granting this access defensible at all.

One leaked key does not need the whole connection rebuilt. pithy dashboard revoke-key stamps that key revoked and leaves everything else in place. Revocation is checked before any validity window, so it takes effect on the next request.

It will take the last live key if you ask it to. Expiry is the orderly end of a rotation and is refused when it would leave nothing live; revocation is the disorderly one — and an adopter holding a leaked key must never be told they have to keep trusting it. The connection then denies every call, which is the correct state for a credential you no longer trust, and connect is the way back.

A trust is revoked the same way, and says what it cannot do. pithy dashboard revoke-trust stops honoring one trust from the next call on, locally, needing nobody. A token cannot be revoked, only the trust, so a token already minted stays usable until it expires — the provider’s lifetime, minutes — and the command says so when it revokes. disconnect says the same when the connection it removes held a live trust.

A second credential kind: an OIDC trust

A key is right for a client somebody runs. It is wrong for an agent nobody watches. A CI job, a container or a scheduled job would have to be handed a private key and keep it, which is key custody with nobody at a terminal. A connection can hold an OIDC trust instead of a key, or beside one: a trusted issuer, the audience its tokens must name, and the claims that say which workload a token was minted for. The workload asks its own identity provider for a short-lived token, and there is no private key to place, rotate or leak.

The claims are the boundary, not the signature. An identity provider signs for every workload it serves with the same keys, so a trust with no claim constraint, or one that names only what the job is — an environment, a branch — and not whose it is, is refused at registration. Prefer an immutable id, such as GitHub’s repository_id, to a name.

Every call is verified on its own, and still names its scope. An identity assertion proves who, not what, so the token alone authorizes nothing: your Worker verifies it per call against the trust’s issuer, audience and claims, and checks the one scope the call names against the connection’s grant, exactly as for a key. Nothing is exchanged for it — an exchange would hand the workload a key to hold, which is the custody a trust exists to remove.

The trust a call names picks its connection. A call carries no connection id, only its trust, so your Worker checks it against the one connection in the environment that holds that trust live, however many connections the environment has. A trust that no connection holds live is refused, and so is one live on two connections, because a trust id names one connection. An environment with no connection at all still answers controlplane/not_connected.

It is written by you, and it cannot be proven at registration. There is no route that registers a trust; pithy dashboard connect --oidc-issuer writes it into your D1 under your signed-in session, and joins the environment’s existing connection when there is one, taking its grant, kind and purpose as they stand. It checks that the issuer’s discovery document resolves and its key set parses, and then reports the trust as awaiting a first call rather than connected, until a call verifies under it.

ESC