Auth proxy

The auth proxy securely creates Swish API tokens on your server using your app secret. The client SDK then uses these tokens to communicate directly with the Swish API. On Shopify themes, token creation is handled automatically by the app proxy. Headless environments - Hydrogen, Next.js, or any custom storefront - need to run their own token endpoint using the @swishapp/auth-proxy package.

If you’re using a Shopify theme, skip this page. Token creation is already handled for you.

Installation

npm install @swishapp/auth-proxy

pnpm add @swishapp/auth-proxy

yarn add @swishapp/auth-proxy

Quick start

Create an auth proxy instance and expose createToken as a server route. The proxy validates the request, creates a token using the Swish API, and returns it to the client.

import { createAuthProxy } from "@swishapp/auth-proxy";

const proxy = createAuthProxy({
  authToken: process.env.SWISH_API_TOKEN,
  authenticate: async (request) => {
    const customerId = await getLoggedInCustomerId(request);
    return customerId;
  },
});

// In your route handler:
const response = await proxy.createToken(request);

Configuration

Option	Type	Required	Description
`authToken`	`string \| (request: Request) => string \| Promise<string>`	Yes	Your Swish API token. Pass a function to resolve the token per-request (e.g. for multi-tenant setups). Must be stored securely and never exposed client-side.
`authenticate`	`(request: Request) => string \| null \| Promise<string \| null>`	Yes	Returns the authenticated Shopify customer ID for the request, or `null` for guest visitors.
`onError`	`(error: unknown) => void`	No	Called when an unexpected error occurs during token creation.
`apiUrl`	`string`	No	Override the Swish API origin the proxy forwards to (default `https://swish.app`, version-routed). When set, requests go to `${apiUrl}/profiles/token` as-is, bypassing version routing. Mainly for local development against a self-hosted Swish API.

How it works

When createToken(request) is called:

The proxy calls your authenticate callback to identify the customer.
It reads the request body and forwards it to POST /profiles/token on the Swish API, authenticated with your authToken.
If the body contains a customer field, the proxy validates that it matches the authenticated customer ID. A mismatch returns a 401 response. This prevents a client from requesting tokens for other customers.
The upstream response is returned directly to the client.

Any unexpected error is passed to onError and returned to the client as a 401.

Framework examples

Hydrogen

Expose the proxy as a Remix action on a server route.

app/routes/api.swish-token.ts

import type { ActionFunctionArgs } from "react-router";
import { createAuthProxy } from "@swishapp/auth-proxy";

const proxy = createAuthProxy({
  authToken: process.env.SWISH_API_TOKEN,
  authenticate: async (request) => {
    const session = await getSession(request);
    return session?.customerId ?? null;
  },
  onError: (error) => console.error("Swish auth proxy error:", error),
});

export async function action({ request }: ActionFunctionArgs) {
  return proxy.createToken(request);
}

Next.js

Expose the proxy as a Route Handler.

app/api/swish-token/route.ts

import { createAuthProxy } from "@swishapp/auth-proxy";

const proxy = createAuthProxy({
  authToken: process.env.SWISH_API_TOKEN!,
  authenticate: async (request) => {
    const session = await getSession(request);
    return session?.customerId ?? null;
  },
  onError: (error) => console.error("Swish auth proxy error:", error),
});

export async function POST(request: Request) {
  return proxy.createToken(request);
}

SDK configuration

Configure the SDK to use your auth proxy route by setting auth.tokenUrl to match the server endpoint you created above.

const swish = await createSwish({
  auth: {
    tokenUrl: "/api/swish-token",
  },
  storefront: { ... },
  context: { ... },
});

On Shopify themes this defaults to /apps/wishlist/api/profiles/token and does not need to be set.

Get started

Features

Customize

Headless

AI tools

Installation

Quick start

Configuration

How it works

Framework examples

Hydrogen

Next.js

SDK configuration

​Installation

​Quick start

​Configuration

​How it works

​Framework examples

​Hydrogen

​Next.js

​SDK configuration

Installation

Quick start

Configuration

How it works

Framework examples

Hydrogen

Next.js

SDK configuration