Integrate Role-Based Access Control

Before you begin

• An organization model. Roles are scoped to an organization, so the same person can be an admin in one tenant and a viewer in another.
• A list of the actions in your product that are worth protecting. Permissions describe actions, not screens.
• A default role for new members. Most products want the least privileged one.
• A decision about session lifetime, because a permission change takes effect when the session next refreshes.

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

RBAC needs no additional credentials. What it does need is a naming convention for permission slugs, chosen before you have fifty of them.

1PAYCUX_API_KEY=sk_example_7f4c1b9ad2e84c6f
2PAYCUX_CLIENT_ID=client_01HQZX8N4T
3PAYCUX_COOKIE_PASSWORD=a-32-character-or-longer-secret

Then, in the dashboard:

1. 1Open Roles and define your permission slugs first. A resource:action shape such as invoices:read reads well in code and sorts sensibly in a list.
2. 2Create the roles your product actually has. Three is usually enough to start; a role per customer request is how this becomes unmanageable.
3. 3Assign permissions to each role, and mark one role as the default for new members.
4. 4Decide which roles an organization admin may hand out themselves, and which stay yours.
5. 5Check the session settings, since a shorter access token lifetime means a revoked permission takes effect sooner.

Implement

There are two places to enforce a permission: in the session, for anything the user does in your product, and against the API, for background work where no session exists. Do both, and never rely on hiding a button.

1import { Paycux } from "@paycux/node";
2import { cookies } from "next/headers";
3 
4const paycux = new Paycux(process.env.PAYCUX_API_KEY);
5 
6export async function requirePermission(permission: string) {
7  const jar = await cookies();
8  const sealed = jar.get("px_session")?.value;
9  if (!sealed) throw new Error("unauthenticated");
10 
11  const session = paycux.userManagement.loadSealedSession({
12    sessionData: sealed,
13    cookiePassword: process.env.PAYCUX_COOKIE_PASSWORD,
14  });
15 
16  const result = await session.authenticate();
17  if (!result.authenticated) throw new Error("unauthenticated");
18 
19  if (!result.permissions.includes(permission)) {
20    throw new Error("forbidden");
21  }
22 
23  return { user: result.user, organizationId: result.organizationId, role: result.role };
24}

1import { requirePermission } from "@/lib/authz";
2 
3export async function GET() {
4  try {
5    const { organizationId } = await requirePermission("invoices:read");
6    const invoices = await listInvoices(organizationId);
7    return Response.json(invoices);
8  } catch (error) {
9    const status = error.message === "forbidden" ? 403 : 401;
10    return Response.json({ error: error.message }, { status });
11  }
12}

1import { Paycux } from "@paycux/node";
2import { requirePermission } from "@/lib/authz";
3 
4const paycux = new Paycux(process.env.PAYCUX_API_KEY);
5 
6export async function POST(request: Request) {
7  await requirePermission("members:manage");
8  const { membershipId, roleSlug } = await request.json();
9 
10  const membership = await paycux.userManagement.updateOrganizationMembership({
11    organizationMembershipId: membershipId,
12    roleSlug,
13  });
14 
15  await paycux.userManagement.revokeSessions({ userId: membership.userId });
16 
17  return Response.json({ ok: true, role: membership.role.slug });
18}

Verify

A permissions test is only meaningful if it asserts a refusal. Verify what a viewer cannot do before you celebrate what an admin can.

1. 1Sign in as a member with the default role and confirm a protected route returns 403 rather than an error page.
2. 2Promote that member to admin, sign in again and confirm the same route now succeeds.
3. 3Call the protected API directly with the member's session, bypassing your UI. It must still refuse.
4. 4Remove a permission from a role while a session is open and confirm the change applies once the session refreshes.
5. 5Open Roles in the dashboard and confirm the permission list matches the slugs your code checks — a typo in a slug fails open in most hand-rolled systems, and this is where you catch it.

Reference

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

Next steps