HTTP routes
Add HTTP endpoints from a plugin — namespaced, secure by default, with typed middleware.
A plugin can contribute HTTP routes through contributes.routes. Each route is mounted
under your plugin's namespace and is secure by default.
Declare a route
definePlugin({
name: "@acme/nextly-plugin-reports",
// ...
contributes: {
routes: [
{
method: "GET",
path: "/summary", // MUST start with "/"
requiredPermission: "read-reports", // secure by default
handler: async (req, ctx) => {
return Response.json({ ok: true });
},
},
],
},
});The route above is served at:
/admin/api/plugins/@acme/nextly-plugin-reports/summaryThat address has two halves, and only the second one is Nextly's.
The namespace is /plugins/<plugin-name><path>, and the plugin name is the raw
package name rather than the admin slug: @acme/p answers at /plugins/@acme/p/export,
even though the admin addresses that plugin as /admin/plugins/acme-p.
The mount is wherever your app puts createDynamicHandlers, and Nextly cannot know
it: the handler is a route file in your app directory. A scaffolded project mounts it at
src/app/admin/api/[[...params]]/route.ts, which is where the /admin/api above comes
from. Move that file and every plugin route moves with it.
A bare /api prefix is not the mount in a scaffolded app. The base template puts only
health and media under /api, with no catch-all, so a plugin route addressed there is
a 404 with nothing to explain it. If your routes are not answering, check where your own
createDynamicHandlers route file actually sits.
Paths support :param segments (/items/:id), captured into ctx.params.
Answering a file at the site root
Some files live at the very root of a site: /robots.txt, /sitemap.xml, /llms.txt. A plugin answers one with a route mounted at the root (mount: "root"), which is served behind the API handler at <mount><path>:
import { definePlugin } from "@nextlyhq/plugin-sdk";
export default definePlugin({
name: "acme-robots",
version: "1.0.0",
nextly: ">=0.0.2",
contributes: {
routes: [
{
method: "GET",
path: "/robots.txt",
mount: "root",
public: true,
handler: () => new Response("User-agent: *\nAllow: /\n"),
},
],
},
});withNextly() rewrites /robots.txt, /sitemap.xml and /llms.txt to that address, so they reach the plugin at the site root. The rewrite is checked after the site's own files and routes: a site that ships its own public/robots.txt or app/robots.ts keeps serving it. So does a site that rewrites one of these files itself, in any phase of its own rewrites(), including a pattern such as /:path* passing everything on to an older site: that file is left to the site's rewrite. Name more files, or a handler mounted somewhere other than /admin/api, with the second argument:
// next.config.ts
import { withNextly } from "nextly/next";
export default withNextly(
{ reactStrictMode: true },
{ apiRoute: "/admin/api", rootFiles: ["/humans.txt"] }
);A root route is matched only after core's own routes decline the path, so a plugin can never take over a core API address this way.
The handler context
A route handler receives the raw web Request plus a PluginRouteContext — your full
plugin ctx (services/db/events/logger/self/…) plus per-request fields:
| Field | Meaning |
|---|---|
ctx.user | The authenticated AuthUser, or null for a public route reached without a session. |
ctx.authenticatedScope | The caller's own grants when they arrived on an API key; undefined for a session or a public route. |
ctx.principal | @experimental The signed-in person of the kind the route asks for in principal, or null. See Signed-in people of your own kind. |
How a permission is spelled
A permission is spelled one way everywhere: read-posts. The database, the
admin's permission matrix, requiredPermission on a route,
ctx.authenticatedScope.permissions and every code-defined access rule all
use it.
Rules were once handed posts:read instead. That spelling is no longer in a
rule's list, so a rule checking it does not allow; check read-posts.
ctx.authenticatedScope.permissions is derived from
ctx.authenticatedScope.grants, the permission rows the key resolved to, so
the two can never name different sets.
Narrowing the scope before a sensitive call
A route may give up part of its own authority for one call. Use narrowScope;
the scope's arrays are frozen, so editing them is refused:
import { narrowScope, type PluginRoute } from "@nextlyhq/plugin-sdk";
const route: PluginRoute = {
method: "PATCH",
path: "/posts/:id",
handler: async (req, ctx) => {
// A SESSION caller carries no scope, so there is nothing to narrow. That is
// safe to pass on — `narrowScope` answers `undefined` for `undefined`, and a
// call with no scope resolves by the caller's own RBAC exactly as it would
// have. Refused here anyway, because THIS route is for API keys: a session
// reaching it would run unnarrowed, and the point of the narrowing is that
// this call is restricted whoever makes it.
const scope = ctx.authenticatedScope;
if (scope === undefined) {
return Response.json({ error: "this route requires an API key" }, {
status: 403,
});
}
const id = ctx.params.id;
const data = (await req.json()) as Record<string, unknown>;
const readOnly = narrowScope(scope, g => g.action === "read");
await ctx.services.collections.updateEntry("posts", id, data, {
as: "user",
user: ctx.user ?? undefined,
authenticatedScope: readOnly, // refused: the scope no longer holds the write
});
return Response.json({ ok: true });
},
};The narrowed scope applies for the whole call, so every check underneath sees
it — the collection gate, each field's access rule, and anything nested. It
can only ever remove authority; a scope cannot grant itself something the key
was not issued.
| ctx.params | Path parameters captured from :param segments. |
Return a standard web Response. A thrown error is isolated into a JSON error response
— a handler failure never crashes the server.
Secure by default
Every route says what reaching it takes, with exactly one of these. A route that declares none could act on the whole site for anyone signed in (an account with no role, or an API key with no grants), so it is refused for every caller, and named in a warning at startup, until it declares one.
- A permission:
requiredPermissionnames the permission a caller needs (see Permissions). Use it for anything that changes or reveals the site's content or settings. - The handler judges each caller: set
checksAccess: trueon a route that acts on the site but whose check depends on the request (such as the collection it names), so a fixedrequiredPermissioncannot express it. Its handler then decides on every request what this caller may do, withctx.caller.can(...)or by calling services as the user. Signing in is still required. - Only the caller's own record: set
siteWide: falseon a route that acts only on the signed-in caller's own record, or only reads what any signed-in caller may see. Being signed in is then all it asks. - Opt out: set
public: trueto make a route callable without a session (e.g. a public sitemap or a webhook receiver).ctx.userwill benull. - Your own signed-in people: set
principal: { kind }to serve a kind of signed-in person your plugin registers instead of staff. The route reads no staff session or API key, and refuses a request with nobody of that kind unlessrequired: false. It cannot be combined withpublicorrequiredPermission. See Signed-in people of your own kind.
A write the session cookie authenticates is also checked for cross-site forgery. Left
unset, csrf checks only the request's origin, which a same-origin write passes;
csrf: true also requires a CSRF token of such a write. A route your admin page writes to through
usePluginRouteMutation works either way, because that hook sends the token on every
write. A page that writes with its own fetch leaves csrf unset, or fetches
/admin/api/auth/csrf and sends the token as x-csrf-token.
writePluginRoute({ plugin, path, method, body }) (experimental) makes one write
outside React, with the same session handling and token. Where
usePluginRouteMutation reports a failure on error at the next render,
writePluginRoute rejects with the parsed error. Use it when you need the reason
at the moment you await, such as to show it beside the field that was refused.
A write through usePluginRouteMutation refreshes the reads it names in
invalidates, in the same tab: a list your page reads with usePluginRoute shows
the change as soon as the write succeeds. writePluginRoute refreshes nothing.
Neither reaches another browser tab. Each tab keeps its own copy of what it read,
so a list open in another tab of the admin still shows what it read before the
write. Reloading that tab reads it again. Opening the page again reads it again
only once its copy is older than the read's staleTime, five minutes by default,
since the admin doesn't re-read on switching tabs. Pass staleTime: 0 to
usePluginRoute for a read that is fetched afresh each time its page opens.
On a public route, csrf: true also checks the origin of a write no session
authenticates, without asking it for a token; only such a write that sends an
Authorization: Bearer token is exempt. A write a session authenticates is
checked as the session's, whatever header it carries. Set it on a public route that browsers
write to, above all one that keeps its own cookie for anonymous visitors, such as
a guest cart. A route for webhooks or other server callers leaves csrf unset.
See Which callers each csrf setting checks
for the full table, and Route protections
for csrf: false and the other options.
Gating on one of your OWN collections
A permission slug spells a collection — and a host can rename your plugin's
collections. So a fixed "create-patterns" demands a grant that was seeded under
a different name on any install that renamed it, leaving a route nobody there can
call.
Give a function instead. It receives your plugin's resolved names and returns the slug to require:
{
method: "POST",
path: "/patterns",
// `collection()` resolves the rename AND composes the slug, so you never
// spell one yourself.
requiredPermission: ({ collection }) => collection("patterns", "create"),
handler: savePattern,
}collection(declaredSlug, action) takes the slug you declared, not the one
the host ended up with. single(declaredSlug, action) does the same for a
Single.
Keep the plain string for a permission that cannot move — one your plugin
declared itself, like "export-submissions".
Two rules for the function:
- It must be pure and synchronous. It runs on every request to the route, before anything about the caller is known — so it is given your names and nothing about the request. Deciding on the caller is the access rule's job, and it runs after authentication rather than before it.
- If it throws, the request is refused. A gate that cannot be worked out never falls back to "no permission required".
{
method: "GET",
path: "/sitemap.xml",
public: true, // no auth — public derived data
handler: async (_req, ctx) => {
const xml = await buildSitemap(ctx.services); // use { as: "system" } inside
return new Response(xml, { headers: { "content-type": "application/xml" } });
},
}Pair public: true with { as: "system" } service calls only for genuinely public,
derived data. For user data, keep the route authenticated and call services with
{ as: "user", user, authenticatedScope }.
An API key is judged on its own grants
ctx.user names the ACCOUNT. When the request arrived on an API key that account is
the key's owner, so a service asked to judge user.id alone would resolve the
owner's roles — and a key scoped to read would be allowed whatever its owner can do.
You do not have to do anything for this. The dispatcher pins the caller's scope
for the length of the request, so an ordinary { as: "user", user } call is judged on
the key's grants:
const posts = await ctx.services.collections.listEntries("posts", {}, {
as: "user",
user: ctx.user ?? undefined,
});ctx.authenticatedScope is there when you want to read it — to log the grants, or to
NARROW them before a particularly sensitive call. Passing it explicitly wins over the
ambient one:
{ as: "user", user: ctx.user ?? undefined, authenticatedScope: ctx.authenticatedScope }A session caller carries no scope at all, and resolves exactly as it always has — super-admin bypass included.
Reading and writing your own route from the admin
A plugin's admin components can call the routes the same plugin contributed
through helpers exported from @nextlyhq/plugin-sdk/admin, so neither half of
the plugin hand-rolls the session, its refresh or the error envelope:
import { usePluginRoute, readPluginRoute } from "@nextlyhq/plugin-sdk/admin";
// In a component: cached and deduplicated like every other admin read.
const list = usePluginRoute({ plugin: "@acme/p", path: "/summary" });
// list.pending until an answer arrives; list.error is `Error | null`.
// Outside React: one read per call. Abort the older read yourself when a
// newer one starts — nothing does it for you, and a stale slow answer that
// is never aborted can land last and overwrite the latest.
let searchRead: AbortController | undefined;
export async function searchPlugins(query: string) {
searchRead?.abort();
searchRead = new AbortController();
return readPluginRoute({
plugin: "@acme/p",
path: `/search?q=${encodeURIComponent(query)}`,
signal: searchRead.signal,
});
}usePluginRoute answers { data, pending, error, refetch, fetching }, and
pending is a real third state beside the data: data being undefined is
both "the route answered nothing" and "the route has not answered yet".
error is an Error or null: a refusal the route answered arrives parsed,
with status, code and data to read, while a request that never got an
answer — offline, a DNS or CORS failure, a cancelled read — stays a native
Error with none of those. readPluginRoute is not cached, answers
undefined for a route that answered with nothing, and rejects the same way:
the parsed error on an HTTP refusal, a native error when the read never got
one. Both go through the same session handling as the admin's own reads, so an
expired session is renewed rather than surfacing as a failure.
Both address the route through the dispatcher's own path builder, so the
address agrees with where the route actually answers — a hand-spelled one is
what drifts when the mount moves. On the default mount that address is
/plugins/<package name><path>; a route the plugin declared with
mount: "root" answers at the path it declared, and the package name plays no
part in its address. The builder only builds: nothing checks that the name a
call passes is the calling plugin's. A path no plugin route and no built-in
endpoint serves is a request failure, not an empty answer — the admin's
catch-all falls through to the built-in parser and refuses it. Writes have
their own pair, usePluginRouteMutation and writePluginRoute, described with
the csrf options above.
Receiving webhooks
Experimental.
ctx.security.webhooksis new and ships@experimental.
A route that receives webhooks is public, since the sender has no session, and
reads the body as the exact bytes sent (rawBody: true). Verify the delivery's
signature before reading anything in it:
import { definePlugin, standardWebhooks } from "@nextlyhq/plugin-sdk";
// Your own record of the delivery ids already handled.
declare function seen(deliveryId: string): Promise<boolean>;
definePlugin({
name: "@acme/nextly-plugin-orders",
version: "1.0.0",
nextly: ">=0.0.2-alpha.0",
// ...
contributes: {
routes: [
{
method: "POST",
path: "/webhooks/orders",
public: true,
rawBody: true,
handler: async (req, ctx) => {
const result = await ctx.security.webhooks.verify(req, {
scheme: standardWebhooks,
// Every secret currently valid: during a rotation, the new and the old.
secrets: [process.env.ACME_ORDERS_SECRET ?? ""],
});
if (!result.verified) {
ctx.logger.warn("Refused an orders webhook", { reason: result.reason });
return new Response(null, { status: 401 });
}
// The same delivery can arrive twice: a sender's retry, or a
// replay. Claim it, so it is processed once.
const claimed = await ctx.security.webhooks.claimDelivery(result, {
provider: "acme-orders",
});
// Processed already: answer as the first time, change nothing.
if (claimed.status === "duplicate") {
return new Response(null, { status: 204 });
}
// Another handler holds it: ask the sender to try again later.
if (claimed.status === "in-progress") {
return new Response(null, { status: 503 });
}
let completed: boolean;
try {
const event = JSON.parse(result.body);
// ... work that is safe to repeat, keyed on result.deliveryId
({ completed } = await claimed.claim.complete());
} catch (error) {
// Give it back, so the sender's retry is processed.
await claimed.claim.release();
throw error;
}
if (!completed) {
// The lease ran out and a retry took the claim over: it may be
// doing this work again right now, which is why the work must be
// safe to repeat. That retry records the outcome; this handler
// must not act on it a second time.
ctx.logger.warn("An orders webhook outlived its lease", {
deliveryId: result.deliveryId,
});
}
return new Response(null, { status: 204 });
},
},
],
},
});Use result.body, the bytes that were verified, rather than reading the request
again. verify reads a copy, so the request stays readable, but only the
verified body is known to be what the sender signed. A verified delivery can
still be a repeat, which is what claimDelivery is for: see
Handling a delivery once.
What core checks, whatever the scheme:
- Age. A delivery signed more than 5 minutes away from now, either way, is
refused as
expired. SettoleranceSecondsto change that; it must be a finite number. - Signatures. Every signature the delivery presents is compared with every secret you pass, as bytes, in constant time. A delivery signed with the old secret or the new one verifies while you pass both.
- Size. A body over 1 MiB is refused as
too-largebefore anything is signed. SetmaxBytesto change that. - Nothing is verified by default. No signature headers is
missing, an unreadable header ismalformed, no usable secret isno-secret, and a signature that matches no secret ismismatch. The reason is for your log; answer the sender with a plain 400 or 401.
A provider's own scheme
standardWebhooks is the scheme Nextly signs its own webhooks
with. For another provider, describe its scheme: where its signatures and
timestamp are, which bytes it signs, and how one secret signs them. Core still
does the age check and the comparison.
import { createHmac } from "node:crypto";
import type { InboundWebhookScheme } from "@nextlyhq/plugin-sdk";
/** `Provider-Signature: t=<seconds>,v1=<hex>`, signing "<t>.<body>". */
const providerScheme: InboundWebhookScheme = {
read({ headers, bytes }) {
const header = headers.get("provider-signature");
if (header === null) return null; // not this scheme's delivery
const parts = header.split(",").map(part => part.split("="));
const t = parts.find(([key]) => key === "t")?.[1];
if (t === undefined || !/^\d+$/.test(t)) throw new Error("no timestamp"); // malformed
return {
timestamp: Number(t),
// The exact bytes sent, not text decoded and encoded again.
signed: Buffer.concat([Buffer.from(`${t}.`), bytes]),
signatures: parts
.filter(([key]) => key === "v1")
.map(([, value]) => Buffer.from(value, "hex")),
};
},
sign: (secret, signed) => createHmac("sha256", secret).update(signed).digest(),
};A provider that signs no time, such as one sending sha256=<hex> over the body
alone, returns timestamp: "none". It has to say so: a scheme that leaves the
timestamp out is refused as malformed. Its verified result says
freshness: "unchecked", against "checked" for every other delivery.
verify gives such a delivery no replay protection: someone who captured
one can send it again at any time, and it still verifies. A "checked" delivery
can be replayed too, but only within the tolerance. Claim every delivery
(below): a claimed delivery sent again is a duplicate for as long as its
record is kept, 30 days after it was processed, and after that the same bytes
are new again. Require result.freshness === "checked" wherever a replay later
than that would do harm.
Handling a delivery once
ctx.security.webhooks.claimDelivery(result, { provider }) claims a verified
delivery once per plugin, provider and delivery. The delivery is the id you
pass, for a provider that puts its id in the body; else the id the scheme read
(webhook-id in Standard Webhooks); else a SHA-256 of the body. An id you
pass overrides the scheme's.
provider is your own name for the sender: an id is unique only within it.
Pass it the result exactly as verify returned it. A copy, or an object built
by hand, is refused, and the delivery claimed is always the one that was
verified.
It answers one of three:
first: process the delivery, then end the claim.duplicate: it was processed already. Answer it as a success, so the sender stops retrying.in-progress: another handler holds it right now. Answer with a status the sender retries, such as 503.
In your transaction. Pass the tx that ctx.db.transaction hands its
callback. The claim then commits with your writes, and is gone if they roll
back, so a failed handler leaves the delivery for the sender's retry. There is
nothing to end:
await ctx.db.transaction(async tx => {
const claimed = await ctx.security.webhooks.claimDelivery(result, {
provider: "acme-orders",
tx,
});
if (claimed.status !== "first") return;
// ... your writes, through tx
});Without one. The claim is a lease, 5 minutes by default (leaseSeconds,
1 to 3600). End it with claim.complete() once the work is done, or
claim.release() to give it back at once. Once completed, a delivery stays
processed: release() then answers { released: false }, so the catch in the
example above is safe even when complete() itself threw. A handler that crashes holding it
costs the sender one retry, never the delivery: a retry during the lease is
in-progress, and the first one after it is first. Set leaseSeconds longer
than your handler takes. Once-only holds while the lease does: a handler that
outlives its lease may still be running when a retry takes the claim over, and
its complete() then returns { completed: false }. The work may have run
twice, so keep its effects safe to repeat. Called without tx
while your code has a transaction open, claimDelivery is refused.
A processed delivery's record is kept 30 days, then removed; so is a claim whose lease ran out 30 days ago. No body is stored.
Middleware
Routes support an ordered, typed middleware chain (onion model). Each middleware calls
next() to continue or returns a Response to short-circuit:
import type { Middleware } from "@nextlyhq/plugin-sdk";
const timing: Middleware = async (req, ctx, next) => {
const res = await next();
res.headers.set("x-handler", "reports");
return res;
};
// route: { method, path, middleware: [timing], handler }See also: Permissions · Data access.