AuthKit Integration

Introduction

AuthKit Integration is part of the Paycux platform. This page explains what it does, when to reach for it, and the smallest working setup you can ship.

Everything below applies to both environments. Build and test in staging, then promote the same configuration to production without changing your code — only the API key and client ID differ.

What’s in the session token

Paycux issues a sealed session cookie alongside the access token. The cookie carries no user data of its own — it is an encrypted pointer that the SDK unseals on each request using your cookie password.

Access tokens are short-lived by design. Refresh them on the server, never in the browser, and treat a failed refresh as a signal to send the user back through sign-in.

Why only organization-scoped roles?

Roles are defined once per project and assigned per organization membership, so the same person can be an admin in one organization and a viewer in another.

Check permissions on the server, in the request path, using the permission slug rather than the role name. Role names change; slugs are stable.

FGA and organization memberships

Assign the users and groups who should have access. Anyone outside the assignment is rejected at the provider, before the request reaches Paycux.

Group names sync as-is. If you use groups to drive roles in your application, map them once in the dashboard under Authorization rather than branching on group names in code.

Two layers of authorization

Every API request is authenticated with a bearer token in the Authorization header. Keys are scoped to a single environment and are shown once at creation — store them in a secret manager, not in source control.

1curl -X GET 'https://api.paycux.com/v1/organizations' \
2  -H 'Authorization: Bearer $PAYCUX_API_KEY'

Groups and group role assignments

Groups and group role assignments applies specifically to AuthKit Integration. It behaves the same in both environments, and the values it depends on are visible in the dashboard for the environment you have selected.

If the behaviour you see does not match this description, check which environment your API key belongs to before anything else — a staging key against production data is the most common cause.

Assigning a resource-scoped role to a group

Assigning a resource-scoped role to a group controls what the credential is allowed to do. Grant the narrowest set that lets the integration work, and widen it deliberately.

Scopes are evaluated at the API boundary, so an over-broad token is a real risk even if your own code never uses the extra capability.

How it integrates with access checks

How it integrates with access checks is handled by AuthKit Integration rather than by your application code. Paycux exposes it through the same API surface as the rest of the platform, so the client you already configured needs no additional setup.

Configuration lives in the dashboard and is versioned per environment. Change it in staging, confirm the behaviour, then apply the same change to production.