Authentication

Every Swish API request requires a Bearer token in the Authorization header. Swish supports two token types depending on where the request originates.

API keys

Use an API key for server-side requests where the token can be kept secret. To request an API key, contact support@swish.app.

API keys grant full access to your store’s Swish data. Never expose them in client-side code, public repositories, or browser requests.

import { createApiClient } from "@swishapp/api-client/2026-07";

const client = createApiClient({
  authToken: "your-api-token",
});

const { data } = await client.items.list();

const response = await fetch("https://swish.app/api/2026-07/items", {
  headers: {
    Authorization: "Bearer your-api-token",
  },
});

const { data } = await response.json();

curl https://swish.app/api/2026-07/items \
  -H "Authorization: Bearer your-api-token"

Client tokens

Use client tokens for browser-side requests. A client token is a short-lived JWT scoped to a single customer or anonymous session. Your server obtains one by calling POST /profiles/token with your API key, then passes it to the client.

Token creation flow

Server requests a token

Your server calls POST /profiles/token with the customer’s Shopify GID. For anonymous visitors, omit the customer field to create a session token.

import { createApiClient } from "@swishapp/api-client/2026-07";

const serverClient = createApiClient({
  authToken: "your-api-token",
});

const { data } = await serverClient.profiles.createToken({
  customer: "gid://shopify/Customer/1234567890",
});

const clientToken = data.token;

const response = await fetch("https://swish.app/api/2026-07/profiles/token", {
  method: "POST",
  headers: {
    Authorization: "Bearer your-api-token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer: "gid://shopify/Customer/1234567890",
  }),
});

const { data } = await response.json();
const clientToken = data.token;

curl -X POST https://swish.app/api/2026-07/profiles/token \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"customer": "gid://shopify/Customer/1234567890"}'

The response includes the token and the associated profile:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "profile": "gid://swish/Session/abc123"
  }
}

Client uses the token

Pass the token to the client and use it for subsequent API requests.

import { createApiClient } from "@swishapp/api-client/2026-07";

const client = createApiClient({
  authToken: clientToken,
});

const { data } = await client.items.list();

const response = await fetch("https://swish.app/api/2026-07/items", {
  headers: {
    Authorization: `Bearer ${clientToken}`,
  },
});

const { data } = await response.json();

curl https://swish.app/api/2026-07/items \
  -H "Authorization: Bearer YOUR_CLIENT_TOKEN"

Auth proxy

On Shopify themes, the Swish app proxy handles token creation automatically. Headless storefronts (Hydrogen, Next.js, or custom frontends) need to run their own auth proxy using the @swishapp/auth-proxy package. The auth proxy stores your API key server-side and creates scoped client tokens on behalf of your customers. Your storefront calls the proxy to obtain a token, then uses that token directly against the Swish API for all subsequent requests.

See the auth proxy guide for full setup instructions with Hydrogen, Next.js, and custom frameworks.

Getting started

Profiles

Items

Lists

Shared lists

Smart lists

Notifications

Orders

Subscriptions

Tracking

API keys

Client tokens

Token creation flow

Auth proxy

​API keys

​Client tokens

​Token creation flow

​Auth proxy

API keys

Client tokens

Token creation flow

Auth proxy