An instance calls another instance through the same proxy endpoint, proving who it is with its worker's session instead of a user credential. The target worker receives the caller as the caller claim of Pinboard-Attestation.
ANY /{namespace}/{id}{rest}
Pinboard-From: /{caller-namespace}/{caller-id}
Pinboard-Session: {sessionId}
Pinboard-Session-Secret: {secret}
Pinboard-Subrequest-Depth: {depth}pinned workers set these headers for you. Send them only from a worker process: the secret is the worker's registration secret.
Request headers
| Header | Type | Required | Description |
|---|---|---|---|
Pinboard-From | string | Yes | The calling instance: /{namespace}/{id}, no trailing path. Its presence turns attestation on. |
Pinboard-Session | string | Yes | The calling worker's sessionId from register. |
Pinboard-Session-Secret | string | Yes | The secret the worker registered with. |
Pinboard-Subrequest-Depth | integer | No | Hops so far, 1–9 digits. Carried to the target as the depth claim. |
All four are stripped before forwarding.
Checks
- The session is live and the secret matches it (constant-time compare).
Pinboard-Fromparses as/{namespace}/{id}with a valid id.- The calling worker registered that namespace, and the caller id is currently placed on that session.
- Depth is at most 50.
- The target namespace is registered by the calling worker; in hostname-aware mode the target's hostname and env must equal the caller's registration.
A request that passes skips the data-plane rule. Placement prefers the caller's own worker, so co-located instances stay on one process when headroom allows.
Example
curl https://pinboard.example.com/threads/t_9c1d/state \
-H "Pinboard-From: /threads/t_8f2a" \
-H "Pinboard-Session: 3f9c0d6e2b1a4c7d8e9f0a1b2c3d4e5f" \
-H "Pinboard-Session-Secret: $WORKER_SECRET" \
-H "Pinboard-Subrequest-Depth: 1"The target worker receives, among others:
{
"aud": "<target sessionId>",
"iat": 1762560000,
"exp": 1762560030,
"caller": "/threads/t_8f2a",
"depth": 1
}Errors
| Status | error | When |
|---|---|---|
403 | caller attestation requires session credentials | Pinboard-Session or Pinboard-Session-Secret missing |
403 | malformed subrequest depth | Depth is not 1–9 digits |
403 | unknown session | Session unknown or expired |
403 | invalid session secret | Secret mismatch |
403 | malformed caller claim | Pinboard-From is not /{namespace}/{id} |
403 | caller placement mismatch | Calling worker did not register the caller's namespace, or the caller id is not placed on it |
403 | target outside caller scope | Target namespace not registered by the calling worker, or hostname/env differ |
508 | subrequest depth exceeded | Depth over 50 |
Pinboard does not increment the depth. The caller sends its own depth plus one; pinned (Python and JS) does this and refuses locally past 50.
In hostname-aware mode the Host header still selects the target hostname. pinned sets it to the worker's registered hostname.