Users and Organizations

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.

Authentication methods

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'

Identity linking

Identity linking applies specifically to Users and Organizations. 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.

Email verification

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.

Domain verification

Domain verification applies specifically to Users and Organizations. 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.

Organizations

An organization is the tenant boundary in Paycux. Connections, directories, roles and audit log streams all hang off an organization, and a user reaches your application through a membership in one.

Create an organization per customer, not per environment. The same organization exists in staging and production with separate configuration.

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.

Organization access

Organization access applies specifically to Users and Organizations. 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.