Integrate AuthKit

Before you begin

• A route that can perform a redirect, and a second route to receive the callback. Nothing else is required on the front end.
• A decision about where people land after signing in. AuthKit returns them to your callback; where they go from there is yours.
• Your logo in SVG or PNG and your brand colour, if you want the screen to match your product on the first run.
• A custom domain if you would rather people never see a Paycux hostname. This is optional and can be added later without changing code.

Install

Every example on this page uses the Node.js client. The same calls exist in the Python, Go, Ruby, PHP and Java SDKs, following the naming conventions of each language.

1npm i @paycux/node

Configure

AuthKit uses the publishable client ID to identify which application's screen to render, and the secret key to complete the exchange on your server. The cookie password encrypts the session that comes back.

1PAYCUX_API_KEY=sk_example_7f4c1b9ad2e84c6f
2PAYCUX_CLIENT_ID=client_01HQZX8N4T
3PAYCUX_REDIRECT_URI=http://localhost:3000/callback
4PAYCUX_COOKIE_PASSWORD=a-32-character-or-longer-secret

Then, in the dashboard:

1. 1Open AuthKit and choose the authentication methods to show: email and password, magic link, social providers, or a combination.
2. 2Upload a logo, set the brand colour and pick light, dark or system appearance. The preview updates as you go.
3. 3Register http://localhost:3000/callback as an allowed redirect URI, and add your production URL before you ship.
4. 4Set the sign-out redirect and, if you have them, your terms and privacy links — they appear under the form.
5. 5Optionally point a subdomain such as auth.yourcompany.example at AuthKit so the whole flow stays on your domain.

Implement

The integration is two routes and one helper. AuthKit handles the form, the password rules, the rate limiting and the enterprise path; your code only ever sees the result.

1import { Paycux } from "@paycux/node";
2 
3const paycux = new Paycux(process.env.PAYCUX_API_KEY);
4 
5export async function GET(request: Request) {
6  const returnTo = new URL(request.url).searchParams.get("returnTo") ?? "/";
7 
8  const url = paycux.userManagement.getAuthorizationUrl({
9    clientId: process.env.PAYCUX_CLIENT_ID,
10    redirectUri: process.env.PAYCUX_REDIRECT_URI,
11    provider: "authkit",
12    state: returnTo,
13  });
14 
15  return Response.redirect(url);
16}

1import { Paycux } from "@paycux/node";
2import { cookies } from "next/headers";
3 
4const paycux = new Paycux(process.env.PAYCUX_API_KEY);
5 
6export async function GET(request: Request) {
7  const params = new URL(request.url).searchParams;
8  const code = params.get("code");
9  if (!code) return Response.redirect("/login");
10 
11  const { sealedSession } = await paycux.userManagement.authenticateWithCode({
12    clientId: process.env.PAYCUX_CLIENT_ID,
13    code,
14    session: { sealSession: true, cookiePassword: process.env.PAYCUX_COOKIE_PASSWORD },
15  });
16 
17  const jar = await cookies();
18  jar.set("px_session", sealedSession, { httpOnly: true, sameSite: "lax", path: "/" });
19 
20  const state = params.get("state");
21  const safe = state && state.startsWith("/") && !state.startsWith("//") ? state : "/";
22  return Response.redirect(safe);
23}

1import { Paycux } from "@paycux/node";
2import { cookies } from "next/headers";
3 
4const paycux = new Paycux(process.env.PAYCUX_API_KEY);
5 
6export async function POST() {
7  const jar = await cookies();
8  const sealed = jar.get("px_session")?.value;
9 
10  if (sealed) {
11    const session = paycux.userManagement.loadSealedSession({
12      sessionData: sealed,
13      cookiePassword: process.env.PAYCUX_COOKIE_PASSWORD,
14    });
15    const url = await session.getLogoutUrl();
16    jar.delete("px_session");
17    return Response.redirect(url);
18  }
19 
20  return Response.redirect("/");
21}

Verify

Check the screen and the session separately. A screen that looks right but leaves a readable cookie behind is not finished.

1. 1Open /login and confirm AuthKit shows your logo, your colour and only the methods you enabled.
2. 2Complete a sign-up, then confirm the callback set an HttpOnly cookie and that your app renders as signed in.
3. 3Sign in again from a private window using a social provider, and confirm the same user record is reused rather than duplicated.
4. 4Visit /login?returnTo=/settings and confirm you land on /settings, then try returnTo=https://example.com and confirm you do not.
5. 5Sign out, press the browser back button and reload. The page must render as signed out.

Reference

Request and response shapes for each of these live in the API reference. Paths are relative to https://api.paycux.com.

Next steps