ProxyToken Authentication

When one instance needs to make an authenticated request to another – for example to download a non-public file – it authenticates itself with a short-lived PROXY token. The PROXY token is not used directly on the resource request; instead it is exchanged at the remote for an access token that the requester then caches and reuses.

How It Works

The PROXY token is a normal action token with t: "PROXY", signed by the requesting tenant’s own key. Its audience is the target instance and it expires after one minute – it exists only to prove “this instance is who it claims to be, right now.”

Instance A (requester)                 Instance B (target)
  |                                       |
  |  Mint PROXY token (1 min, aud=B)      |
  |                                       |
  |  GET /api/auth/access-token?token=... |
  |-------------------------------------->| verify PROXY token
  |                                       | (fetch A's key from /api/me,
  |                                       |  check signature + audience)
  |<-- 200 { token: <access-token> } -----| mint scoped access token
  |                                       |
  |  GET /api/files/... (Bearer access)   |
  |-------------------------------------->| validate access token
  |<-- 200 { file data } -----------------|
  1. Mint PROXY token – A creates a one-minute PROXY action token addressed to B.
  2. Exchange – A calls GET https://cl-o.{B}/api/auth/access-token?token=<proxy> (optionally with &subject=...). B verifies the PROXY token against A’s public key and returns a regular access token.
  3. Use the access token – A sends subsequent requests with Authorization: Bearer <access-token>. B validates it like any local session token.

Caching and Retry

The exchanged access token is cached per (tenant, target) and reused for further federated calls, so the PROXY exchange happens only on a cache miss. If a request comes back 401 or 403, the requester invalidates the cached token, mints a fresh one, and retries the request once. The cache TTL follows the access token’s own expiry.

Use Cases

PROXY-token-backed requests are used wherever a remote endpoint requires authentication, such as:

  • File fetching – downloading non-public attachments from a remote instance
  • Authenticated profile and data queries

Endpoints that are open to any instance (such as the profile/key endpoint GET /api/me used during signature verification) are fetched without a token.

See Also