Bubble Plugin

Introduction

This guide connects Bubble Plugin to Paycux over HRIS. Work through it once per organization — each customer gets their own connection, with its own values.

You configure two sides: the application inside the provider, and the connection inside the Paycux dashboard. Neither side is complete on its own, so keep both tabs open.

What Paycux provides

Paycux generates two values for every connection and shows them in the dashboard under the connection's settings. You paste these into the identity provider when you configure the application:

Both values are per connection. Do not reuse them across organizations — each organization gets its own connection and its own pair.

What you'll need

Before you start, make sure you have the following in place:

• A Paycux account with access to the project you are configuring.
• An API key for the environment you are working in. Staging keys start with sk_test_; production keys start with sk_live_.
• Admin access on the system you are connecting, so you can create the application and read its metadata.
• A redirect URI registered in the Paycux dashboard under Developer → Redirects.

Install the Paycux SSO and API Plugins

Install the SDK with your package manager, then read the API key from the environment rather than hard-coding it.

1npm install @paycux/node

Single Sign-On

In Bubble Plugin, complete this step before moving on. The values Paycux generated for this connection are on the connection page in the dashboard — copy them from there rather than retyping.

Use SSO in a Workflow

Use SSO in a Workflow applies specifically to Bubble Plugin. 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.

Directory Sync

Directory Sync keeps your user list in step with the customer's directory. Paycux receives create, update and delete operations and normalizes them into a single shape regardless of the source system.

Deletes arrive as deactivations. Treat a deactivated user as a user who can no longer sign in, and decide separately whether to delete their data.

Enable backend workflows

Enable backend workflows applies specifically to Bubble Plugin. 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.

Create a new workflow to receive webhooks

Webhooks deliver each event to your endpoint over HTTPS with a signature header. Verify the signature before you trust the body, and respond with a 2xx status within thirty seconds.

Delivery is at-least-once, so make your handler idempotent — key it on the event ID and ignore an ID you have already processed. Failed deliveries retry with exponential backoff for twenty-four hours.

Implement the webhook validation action

Implement the webhook validation action is delivered as an event you can subscribe to. Events carry the object as it looked after the change, plus the actor that caused it.

Subscribe to the specific event types you handle rather than all of them — a wildcard subscription turns every new event type into unexpected traffic.

Reconcile the users

A user record holds the identity Paycux resolved for the person: email, name, verification state, and the identities they have linked. It is the object your application should key on.

Users are unique by email within a project. When the same person arrives through a second provider, Paycux links the identity to the existing user rather than creating a duplicate.

Admin Portal

Admin Portal is a hosted set of screens your customers use to configure their own connection. You generate a signed link, they finish the setup, and you stay out of the email thread.

Links are single-purpose and expire. Generate one per task — SSO setup, directory setup, domain verification — rather than one link for everything.

Verify the connection

Verify the setup end to end before you hand it to a customer. Run the flow from a private browser window so no existing session masks a broken step.

1. 1Open the connection in the dashboard and confirm its status reads Active.
2. 2Start the flow from your application, not from the provider, so the redirect URI is exercised.
3. 3Sign in as a test user and confirm the profile arrives with an email address.
4. 4Check the connection's event list — a successful sign-in appears within a few seconds.

Troubleshooting

If something does not work, check these first — they cover the large majority of failed setups:

• The values were pasted into the wrong environment. Staging and production hold separate configuration.
• A trailing slash or stray whitespace in the ACS URL or redirect URI. Both are matched exactly.
• The connection is saved but not activated. An inactive connection returns connection_inactive.
• Attribute names differ from what the mapping expects, so the user is created without an email address.

Every failed authentication is recorded with a reason on the connection's page in the dashboard. Start there before reading application logs.