Authentication

Pinboard identifies callers with Passport, configured in PINBOARD_PASSPORT. Passport answers who the caller is; Pinboard decides what they may do.

Sending a credentialCopy Anchor Link

By default every provider reads a bearer token:

curl https://pinboard.example.com/registry/workers \
  -H "Authorization: Bearer $PINBOARD_OPERATOR_TOKEN"

A provider can read a cookie or a named header instead (credential: {cookie: "name"} or {header: "name"}).

Resolution order:

1. Providers run in config order, staticToken providers first.
2. A provider with no credential in its location is skipped.
3. A jwt provider skips a token whose iss is not its issuer.
4. A staticToken provider skips a token that matches none of its keys.
5. The first provider that accepts the credential names the principal. One that rejects it fails the request.
6. No provider accepting means no credential: anonymous.

Registry rolesCopy Anchor Link

A credential needs the exact scope of the route; pinboard:operator does not imply pinboard:worker.

The pinboard claimCopy Anchor Link

Registry access is scoped by the principal's claims.pinboard object:

Host rules in allowedBackendHosts, hostnames and envs:

For operators, absent hostnames and envs mean unrestricted.

{
  "name": "fleet-worker",
  "token": { "env": "PINBOARD_WORKER_TOKEN" },
  "scopes": ["pinboard:worker"],
  "claims": {
    "pinboard": {
      "namespaces": ["/threads"],
      "allowedBackendHosts": [".workers.internal"],
      "allowedPorts": [8000]
    }
  }
}

Registry auth errorsCopy Anchor Link

Out-of-scope request bodies answer 403 with a specific message; see each endpoint.

Account ownershipCopy Anchor Link

Register stores the principal's sub as the worker's account. heartbeat, release, tag and deregister require the same sub, else 403 {"error":"forbidden"}. Operator routes judge only the claim scope, never the account.

Data-plane rulesCopy Anchor Link

The namespaces object in PINBOARD_PASSPORT turns on data-plane checks. Without it, every routed request passes.

{
  "providers": [ ... ],
  "namespaces": {
    "/threads": { "allow": ["threads:write"] },
    "/public": { "allow": "anonymous" },
    "*": { "allow": "authenticated" }
  }
}

• The exact namespace key wins over "*". A namespace matching neither is denied.
• Scopes starting pinboard: are reserved; the config is rejected at boot.
• A credential a provider rejects fails the request even under "anonymous".

Instance attestationCopy Anchor Link

An instance calling another instance through Pinboard proves its identity with its worker session instead of a Passport credential. See Call from an instance.

What workers receiveCopy Anchor Link

Pinboard strips every inbound Pinboard-* header and stamps its own. Workers trust only these.

Attestation JWS: header {"alg":"HS256","typ":"pinboard+jwt"}.