API and SDK

The admin app exposes one procedure layer through two transports:

• oRPC RPC at /api/orpc, used by the admin UI with session cookies.
• OpenAPI REST at /api/{organizationSlug}/... (or /api/... for endpoints that use the active organization), used by the SDK, external consumers, and the generated reference.

Both transports use the same router, context, validators, and services.

API layout

apps/admin/
  orpc/
    base.ts          # context + public/protected/org/apiKey procedures
    routers/         # module routers
    permissions.ts   # procedure path → permission mapping
  app/api/
    orpc/[...rest]/  # RPC handler for the admin client
    [...orpc]/       # OpenAPI handler for REST clients
    openapi.json/    # generated OpenAPI document

The OpenAPI handler adds CORS and serves the spec. The RPC handler is used with credentials: "include" from the admin client.

Authentication

REST requests authenticate with the ApiKey header:

curl http://localhost:3000/api/my-store/products \
  -H "ApiKey: sk_live_..."

Session cookies also work for requests made from the admin app. API keys are scoped to one organization and must match the slug in the path.

Common query parameters

List endpoints accept pagination and ordering parameters:

Responses return the list plus pagination metadata from the query layer. Check the generated reference for each endpoint's exact input.

Error format

Errors use HTTP status codes and a JSON body with a message:

{
  "message": "Unauthorized"
}

The SDK converts non-2xx responses into SDKError and preserves the message.

OpenAPI and docs

• The generated spec is available at /api/openapi.json.
• The admin has an in-app Scalar reference at /[locale]/docs.
• This site's API reference is generated from the same spec.

To refresh the docs snapshot:

pnpm docs:sync-api

The sync script fetches the spec from the running admin app, tags operations by module, rewrites the public server URL, and regenerates the reference pages. Do not edit generated API pages by hand.

SDK

@prolifto/sdk is a typed HTTP client used by the storefront.

import { ProliftoClient, SDKError } from "@prolifto/sdk";

const client = new ProliftoClient({
  apiKey: process.env.API_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_API_URL,
  orgSlug: process.env.ORGANIZATION_SLUG!,
});

const { data: products } = await client.products.getAll({
  limit: 20,
  page: 1,
});

The SDK exposes resource clients such as products, categories, collections, orders, customers, addresses, coupons, invoices, receipts, media, billboards, shipping, and health.

Configuration

The client sends ApiKey and Content-Type headers, retries transient failures up to three times with exponential backoff, and uses a 30-second timeout.

Error handling

try {
  await client.products.getAll();
} catch (error) {
  if (error instanceof SDKError) {
    console.error(error.message);
    console.error(error.cause);
  }
}

Adding an endpoint

1. Add the Zod input schema to @prolifto/domain.
2. Add the procedure to the module's server/procedures.ts.
3. Choose publicProcedure, protectedProcedure, orgProcedure, or apiKeyProcedure.
4. Map the procedure path to a permission in orpc/permissions.ts.
5. Register the router in orpc/routers.
6. Add a service/query and tests.
7. Run pnpm docs:sync-api so the reference includes the endpoint.

Stability

Operation IDs are used by generated docs and clients. Renaming one is a breaking change. Treat request shapes, response shapes, and permissions as contracts when changing an existing endpoint.

Related

• Authentication and tenancy
• API reference
• Project structure