Pod-app sign-in

@synap-core/sdk/connect lets one app work on many pods: each person signs in with their own pod, chooses the spaces the app may use, and can take that access back. The app is an OAuth 2.1 public client of each pod (PKCE S256, the pod's iss checked on every answer). Its client ID is the https URL of a client metadata document that the app serves itself, so there is nothing to register on a pod. The pod's token stays on your server, sealed in an HTTP-only cookie; the browser never sees it.

This page is the reference. To build an app step by step, follow Build a website on your pod. The AGENTS.md file shipped in the npm package has every rule in full.

The entry is server-only: it throws when loaded in a browser, and a browser bundle resolves it to a stub that throws. It uses Web-standard Request, Response and WebCrypto, so it runs in Next.js route handlers and proxy.ts, Hono, Remix and edge runtimes. It needs Node.js 20 or later.

Set up: createPodAppAuthCopy Anchor Link

import { createPodAppAuth } from "@synap-core/sdk/connect";

export const synap = createPodAppAuth({
  appUrl: process.env.SYNAP_APP_URL!, // https://notes.example.com
  clientName: "Notes",
  requests: [
    { permission: "entity.note.read", reason: "Show your notes" },
    { permission: "entity.note.create", reason: "Save the notes you write here" },
  ],
  secret: process.env.SYNAP_APP_SESSION_SECRET!,
});

createPodAppAuth refuses at startup, with a ConnectError whose code is misconfigured, every setup the pod would refuse at sign-in, so the mistake shows when your app starts, not when a person connects. The client metadata document must stay under 8 KB.

RoutesCopy Anchor Link

Three more paths are pages of your app: /connect (the connect page; the pod may send people there to start a sign-in), /connect/result (where a failed callback lands with ?error=<code>) and / (where a sign-in lands when it named no next). Each route file re-exports one handler, for example export const POST = synap.handlers.connect;.

connect and disconnect change state, so they accept a POST from your own pages only (the Origin header, or Sec-Fetch-Site: same-origin). The connect form sends:

Before it sends the browser anywhere, the SDK reads the pod's OAuth metadata and checks that it is a Synap pod that supports app sign-in. It never follows a redirect from the pod: a pod that moved answers pod_moved, and the person connects again with the new address. The connect route fetches an address a visitor typed, so rate-limit it per visitor.

PermissionsCopy Anchor Link

Each request names one permission in the pod's grammar, <subject>[.<qualifier>].<action>, lowercase, as in API key grants, and the sentence the consent screen shows (reason, 1 to 200 characters). The person ticks what the app gets; asking is not getting.

A pod-wide read comes back as a grant row with no space: listEntities({ profileSlug }) with no workspaceId then lists that kind across the pod. Writes always name a space the person granted.

The connectionCopy Anchor Link

After sign-in the connection holds the pod's URL, the person (user), the grant by space and the tokens.

Read the connection where you have the request, or its Cookie header:

const connection = await synap.readConnection((await headers()).get("cookie"));
if (!connection) redirect("/connect");

synap.readLapsed(cookieHeader) answers { podUrl } when this browser was connected to a pod and the connection lapsed, so you can say "expired, connect again" with the address pre-filled.

RenewalCopy Anchor Link

A server component cannot set cookies, so renew in proxy.ts (or a route handler) before the page renders: synap.refreshIfNeeded(request) rotates the token only in its last 5 minutes, and only once at a time per connection in the process. Send outcome.setCookies on the response and forward outcome.cookieHeader as the request's Cookie. Build a website on your pod has the full proxy.ts, with the matcher that skips static files, the sign-in routes and router prefetches.

In a route handler or a server action, synap.client(connection, { request, persist }) renews once after a 401 and retries the request once; persist receives the Set-Cookie values to send. Without persist (a server component), a 401 answers unauthorized with refreshable: true: send the visitor through the proxy with refreshIfNeeded(request, { force: true }).

The client: synap.client(connection)Copy Anchor Link

const pod = synap.client(connection);

const notes = await pod.listEntities({ workspaceId, profileSlug: "note", limit: 50 });
if (!notes.ok) console.warn(notes.error.code);

const res = await pod.post("/entities", { profileSlug: "note", workspaceId, title: "Hello" });
if (res.ok && res.status === "proposed") showPending(res.reviewUrl);

Calls never throw: a read answers { ok: true, data } or { ok: false, error }. A write answers one of:

get, post, patch, put and delete take a Hub REST path (/entities, not /api/hub/entities); see the Hub REST API. Encode each path segment with encodeURIComponent: a path that could leave the Hub answers invalid without a request. Typed reads include listEntities, getEntity, getEntityConnections, getDocument, getFileUrl and listPendingProposals (needs proposal.read).

Client options: timeoutMs (default 10 000; a slower request answers pod_unreachable), maxResponseBytes (default 8 MiB; a bigger answer is server) and retryRateLimitedWithinSec (default 0: a GET answered 429 with a wait at most this long is asked once more after the wait; writes are never retried).

Rate limitsCopy Anchor Link

A pod budgets the calls each connection makes in a 15-minute window, with separate budgets for reads and writes (by default 3,000 reads and 500 writes; the pod's owner can change them). Over the budget, every call answers rate_limited with retryAfterSec until the window ends. Read a list once per page and keep it for that request, rather than asking again.

Error codesCopy Anchor Link

A call's error is { code, status, retryAfterSec?, detail?, podCode?, reason? }. Branch on code; detail and podCode are for your logs. status is null when nothing was answered, and reason is set when the SDK refused without sending anything (not_granted, agent_cannot_approve, invalid_input). POD_ERROR_CODES lists every code.

A sign-in that fails redirects with ?error=<code>: to your connect page when it could not start, to your result page when it failed on the way back. parseConnectErrorCode(value) reads it back (null for anything else).

Synap CloudCopy Anchor Link

With cloudUrl set, synap.cloudConnectAvailable is true and the app can offer "Continue with Synap Cloud": a POST to handlers.cloudConnect sends the browser to the Synap Cloud pod chooser, which returns to your connect page. There, acceptLaunch(url, origin).cloudState is set: forward the request's query to handlers.cloudReturn, which checks the return against this browser's cookie before the chosen pod is used, then signs in as with a typed address.

const launch = acceptLaunch(url, origin);
if (launch.cloudState) redirect(`${synap.paths.cloud}${new URL(url).search}`);

Your own storeCopy Anchor Link

By default the connection lives in the sealed cookie. To keep it in a database or a key-value store, implement ConnectionStore and pass it as store:

interface ConnectionStore {
  read(request: Request): Promise<PodConnection | null>;
  write(connection: PodConnection, request: Request): Promise<string[]>; // Set-Cookie values
  clear(request: Request): Promise<string[]>;
}

A shared server-side store also protects a connection served by several server instances: the pod revokes a connection when a spent refresh token is presented again, and only one store all instances read can rule that out.

Test without a podCopy Anchor Link

@synap-core/sdk/testing has createMockAuthServer(), a mock pod with the metadata, the consent step, the token, refresh and revoke endpoints and the Hub doors an app uses, and createMockCloud() for the Synap Cloud chooser. Pass the mock's fetch to createPodAppAuth; the mock answers in memory, so your app can run on http://localhost. A real pod, even a local one, accepts only an app served over https: use a tunnel in development.

import { createMockAuthServer } from "@synap-core/sdk/testing";

const pod = createMockAuthServer({ actsAs: "agent" });
const synap = createPodAppAuth({ ...config, fetch: pod.fetch });

RelatedCopy Anchor Link

• Build a website on your pod
• API keys
• Permission model
• Hub REST API