Integrate Role-Based Access Control

Before you begin

• A Paycux workspace with at least one project and environment. Create one at /dashboard/connect.
• A dashboard session for console calls. The __Host-paycux_session cookie is issued by the sign-in flow; the examples pass it with curl --cookie.
• A realm access token for end-user calls. Your application obtains it from the environment's identity realm; its e-mail address must be verified.
• An understanding that roles are fixed: owner, admin, developer, billing and viewer in the workspace; owner, admin and member in an organisation.

Install

There is nothing to install. Paycux is a plain HTTPS JSON API, so every example on this page uses curl. Console routes send the dashboard session cookie, end-user routes send the application's realm access token as a bearer credential, and agent routes send the short-lived agent token. The routes that exist today are listed on What exists today.

1# Console routes carry the dashboard session cookie set by sign-in
2curl https://api.paycux.com/v1/auth/session \
3  -H "Cookie: __Host-paycux_session=<session>"
4 
5# End-user routes carry the application's realm access token
6curl https://api.paycux.com/v1/<end-user route> \
7  -H "Authorization: Bearer <realm access token>"

Configure

No credential is specific to roles. Console requests carry the dashboard session cookie; end-user requests carry a realm access token. Keep the identifiers of your project, environment and realm in your application's configuration.

1PAYCUX_API_BASE_URL=https://api.paycux.com
2PAYCUX_PROJECT_ID=<project id>
3PAYCUX_ENVIRONMENT_ID=<environment id>
4PAYCUX_REALM_ID=<realm id>

Then, in the dashboard:

1. 1Open Settings and invite your team with the role each person needs. Viewer and developer can read; billing manages the workspace plan; owner and admin manage members and configuration.
2. 2Call GET /v1/auth/session with a signed-in member's cookie to see the role the API enforces for that session.
3. 3On the environment's Organisations tab, review the organisations your end users created and the roles their members hold.
4. 4Define plan entitlements in the environment catalog; usage decisions for end-user accounts come from them.

Implement

There are three checks you can make today: the workspace role of a console session, the organisation role of an end user, and the entitlement decision for a usage event. Permission claims in tokens and a policy evaluation endpoint are planned, so do not design for them yet.

1curl https://api.paycux.com/v1/auth/session \
2  --cookie "__Host-paycux_session=<session cookie>"
3 
4HTTP 200
5{
6  "workspaceId": "3f9d2c1e-5b7a-4c8d-9e0f-1a2b3c4d5e6f",
7  "actorId": "6d1f0b2e-3c4a-4d5e-8f60-7a8b9c0d1e2f",
8  "role": "admin"
9}

1curl -X PATCH https://api.paycux.com/v1/workspace/members/9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d \
2  --cookie "__Host-paycux_session=<session cookie>" \
3  -H "Content-Type: application/json" \
4  -d '{ "role": "developer" }'
5 
6HTTP 200
7{
8  "id": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
9  "email": "[email protected]",
10  "displayName": "Dana",
11  "role": "developer",
12  "status": "active",
13  "emailVerified": true,
14  "lastLoginAt": "2026-10-11T16:40:12.004Z",
15  "createdAt": "2026-09-30T08:02:55.310Z"
16}

1curl "https://api.paycux.com/v1/billing/organizations/c2b1a0f9-8e7d-4c6b-9a5f-4e3d2c1b0a99/members?projectId=a1000000-0000-4000-8000-000000000002&environmentId=a1000000-0000-4000-8000-000000000003&realmId=a1000000-0000-4000-8000-000000000004" \
2  -H "Authorization: Bearer <realm access token>"
3 
4HTTP 200
5{
6  "billingAccountId": "c2b1a0f9-8e7d-4c6b-9a5f-4e3d2c1b0a99",
7  "role": "admin",
8  "members": [
9    {
10      "identityId": "7a6b5c4d-3e2f-4a1b-9c0d-8e7f6a5b4c3d",
11      "role": "owner",
12      "status": "active",
13      "joinedAt": "2026-10-12T09:14:03.220Z"
14    },
15    {
16      "identityId": "2c3d4e5f-6a7b-4c8d-9e0f-a1b2c3d4e5f6",
17      "role": "admin",
18      "status": "active",
19      "joinedAt": "2026-10-12T10:02:41.117Z"
20    }
21  ],
22  "invites": [
23    {
24      "inviteId": "e4d3c2b1-a098-4f7e-8d6c-5b4a39281706",
25      "email": "c***@robotics.example",
26      "role": "member",
27      "expiresAt": "2026-10-19T09:14:03.220Z"
28    }
29  ]
30}

1const response = await fetch(process.env.PAYCUX_API_BASE_URL + "/v1/usage/events", {
2  method: "POST",
3  headers: {
4    Authorization: "Bearer " + realmAccessToken,
5    "Idempotency-Key": "usage-" + requestId,
6    "Content-Type": "application/json",
7  },
8  body: JSON.stringify({
9    projectId: process.env.PAYCUX_PROJECT_ID,
10    environmentId: process.env.PAYCUX_ENVIRONMENT_ID,
11    realmId: process.env.PAYCUX_REALM_ID,
12    billingAccountId,
13    meterKey: "api_calls",
14    quantity: 1,
15    occurredAt: new Date().toISOString(),
16  }),
17});
18 
19// { allowed, reason, consumed, limit, eventId, duplicate }
20const decision = await response.json();
21 
22if (!decision.allowed) {
23  // LIMIT_EXCEEDED, NO_ENTITLEMENT or SEAT_REQUIRED
24  return refuse(decision.reason);
25}

Verify

Verify refusals before successes: a role check that never says no is not a check.

1. 1Sign in as a viewer and call PATCH /v1/workspace/members/:memberId. Expect 403 FORBIDDEN.
2. 2As an admin, try to grant owner to another member. Expect 403; as an owner, expect 200 and a workspace_member.role_changed event in the audit ledger.
3. 3Remove a member and confirm revokedSessions in the response; their next console request answers 401.
4. 4As an end user with role member, create an invite for the organisation. Expect 403 INVALID_SCOPE.
5. 5Report usage past the plan limit and confirm allowed is false with reason LIMIT_EXCEEDED.

Reference

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

Next steps