Integrations

Integrate Organization Setup

Organisations are created by your end users through the API, invites are single-use tokens your application delivers, and your team registers applications and reviews organisations from the console. A self-serve portal for your customer's IT administrator is planned; nothing on this page depends on it.

Available in part — Organization Setup: End users create organisations, invite members and accept by verified e-mail today, and operators see those accounts in the console; a guided setup flow for identity connections, with its completion and recovery states, is planned. Items listed as planned below cannot be enabled yet. What Paycux provides today.

Before you begin

A registered application: a project with an environment, created at /dashboard/connect or with POST /v1/applications.
Ready identity setup for the environment, so your users can obtain realm access tokens with a verified e-mail address.
A way to deliver an invite token to the invited person. Paycux returns organisation invite tokens once and does not e-mail them.
A dashboard session for console calls, passed as the __Host-paycux_session cookie.

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.

terminal

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

Your application needs the identifiers of the project, environment and realm it runs in. Every end-user request carries them, and the API refuses a scope that does not match the token.

.env.local

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:

1Open /dashboard/connect, enter the application name, address and identity mode, and choose the environment. Only owners can create a production environment.
2On the environment's Setup tab, review the saved configuration and select the Paddle connection once one exists.
3On the environment's Organisations tab, open an organisation to see its members and pending invites with masked e-mail addresses.
4Revoke a pending invite from the console when your customer asks for it. The action is audited with your member id and via: dashboard.

Implement

Three calls cover the end-user side: create an organisation, invite a colleague and accept the invite. Each carries the realm access token and the project, environment and realm of that token.

Create an organisation

The caller becomes the owner. The scope in the body must match the token's project, environment and realm, otherwise the API answers 400 INVALID_SCOPE.

terminal

1curl -X POST https://api.paycux.com/v1/billing/organizations \
2  -H "Authorization: Bearer <realm access token>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "projectId": "a1000000-0000-4000-8000-000000000002",
6    "environmentId": "a1000000-0000-4000-8000-000000000003",
7    "realmId": "a1000000-0000-4000-8000-000000000004",
8    "displayName": "Example Robotics"
9  }'
10 
11HTTP 201
12{
13  "billingAccountId": "c2b1a0f9-8e7d-4c6b-9a5f-4e3d2c1b0a99",
14  "kind": "organization",
15  "role": "owner"
16}

Invite a colleague

Owners and admins invite with role member or admin. The token is returned exactly once: store nothing and hand it to the invitee through your own channel. An address that already belongs to an active member or has a pending invite answers 409.

terminal

1curl -X POST https://api.paycux.com/v1/billing/organizations/c2b1a0f9-8e7d-4c6b-9a5f-4e3d2c1b0a99/invites \
2  -H "Authorization: Bearer <realm access token>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "projectId": "a1000000-0000-4000-8000-000000000002",
6    "environmentId": "a1000000-0000-4000-8000-000000000003",
7    "realmId": "a1000000-0000-4000-8000-000000000004",
8    "email": "colleague@robotics.example",
9    "role": "member"
10  }'
11 
12HTTP 201
13{
14  "inviteId": "e4d3c2b1-a098-4f7e-8d6c-5b4a39281706",
15  "token": "<single-use token, returned once>",
16  "role": "member",
17  "expiresAt": "2026-10-19T09:14:03.220Z"
18}

Accept the invite

The invitee calls accept with their own realm access token. Their verified e-mail address must equal the invited one; otherwise the API answers 403 without revealing the address. Expired, revoked or already accepted invites answer 409, unknown tokens 404.

terminal

1curl -X POST https://api.paycux.com/v1/billing/invites/accept \
2  -H "Authorization: Bearer <realm access token of the invitee>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "projectId": "a1000000-0000-4000-8000-000000000002",
6    "environmentId": "a1000000-0000-4000-8000-000000000003",
7    "realmId": "a1000000-0000-4000-8000-000000000004",
8    "token": "<single-use token>"
9  }'
10 
11HTTP 200
12{
13  "billingAccountId": "c2b1a0f9-8e7d-4c6b-9a5f-4e3d2c1b0a99",
14  "role": "member",
15  "status": "active"
16}

Register an application from your own tooling

The console does this for you at /dashboard/connect. From a script, generate both UUIDs first and keep them: an identical retry returns the same ids with 200 and created: false, a changed body or a reused slug answers 409, and a project beyond the plan limit answers 402.

terminal

1curl -X POST https://api.paycux.com/v1/applications \
2  --cookie "__Host-paycux_session=<session cookie>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "projectId": "a1000000-0000-4000-8000-000000000002",
6    "environmentId": "a1000000-0000-4000-8000-000000000003",
7    "name": "Example Robotics",
8    "slug": "example-robotics",
9    "environmentName": "development",
10    "applicationUrl": "https://app.robotics.example/",
11    "identityMode": "external"
12  }'
13 
14HTTP 201
15{
16  "projectId": "a1000000-0000-4000-8000-000000000002",
17  "environmentId": "a1000000-0000-4000-8000-000000000003",
18  "created": true
19}

Verify

Walk the invitation as an end user would, then check what your team can and cannot see.

1Create an organisation with one test identity and confirm GET /v1/billing/accounts lists it with role owner.
2Invite a second address and accept with a token whose e-mail does not match. Expect 403; accept with the right identity and expect status active.
3Reuse the accepted token. Expect 409.
4Open the organisation in the console and confirm e-mail addresses are masked and no token is shown.
5Revoke a pending invite from the console and confirm organization_invite.revoked appears in the audit ledger with via: dashboard.

Connect an applicationRegister a project, its first environment and the setup draft in one step.

Reference

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

Method	Path	What it does
POST	/v1/billing/organizations	Create an organisation; the caller becomes owner (realm token).
GET	/v1/billing/accounts	Accounts and roles of the calling identity (realm token).
POST	/v1/billing/organizations/:billingAccountId/invites	Invite with role member or admin; token returned once (organisation owner/admin).
POST	/v1/billing/invites/accept	Accept an invite with a matching verified e-mail address.
POST	/v1/billing/organizations/:billingAccountId/invites/:inviteId/revoke	Revoke a pending invite (organisation owner/admin).
GET	/v1/billing/organizations/:billingAccountId/members	Members of the organisation; pending invites included for owner/admin.
GET	/v1/environments/:environmentId/organizations	Console: organisations of the environment with member and invite counts (session cookie).
GET	/v1/environments/:environmentId/organizations/:billingAccountId	Console: one organisation with masked members and invites.
POST	/v1/environments/:environmentId/organizations/:billingAccountId/invites/:inviteId/revoke	Console: revoke a pending invite (workspace owner/admin).
POST	/v1/applications	Register a project, its first environment and the setup draft (owner/admin).
GET	/v1/environments/:environmentId/setup	Read the saved setup draft, or { setup: null }.
PUT	/v1/environments/:environmentId/setup	Save the setup draft with expectedRevision (owner/admin).

Next steps

Role-Based Access Control integrationWorkspace roles, organisation roles and entitlement decisions.Audit Logs integrationWhere every invite, acceptance and revocation is recorded.What exists todayEvery implemented route, rendered from the API contract.Organization Setup overviewWhat exists today and what is planned.

Integrations

Integrate Organization Setup

Before you begin

A registered application: a project with an environment, created at /dashboard/connect or with POST /v1/applications.
Ready identity setup for the environment, so your users can obtain realm access tokens with a verified e-mail address.
A way to deliver an invite token to the invited person. Paycux returns organisation invite tokens once and does not e-mail them.
A dashboard session for console calls, passed as the __Host-paycux_session cookie.

Install

terminal

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

Your application needs the identifiers of the project, environment and realm it runs in. Every end-user request carries them, and the API refuses a scope that does not match the token.

.env.local

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:

1Open /dashboard/connect, enter the application name, address and identity mode, and choose the environment. Only owners can create a production environment.
2On the environment's Setup tab, review the saved configuration and select the Paddle connection once one exists.
3On the environment's Organisations tab, open an organisation to see its members and pending invites with masked e-mail addresses.
4Revoke a pending invite from the console when your customer asks for it. The action is audited with your member id and via: dashboard.

Implement

Three calls cover the end-user side: create an organisation, invite a colleague and accept the invite. Each carries the realm access token and the project, environment and realm of that token.

Create an organisation

The caller becomes the owner. The scope in the body must match the token's project, environment and realm, otherwise the API answers 400 INVALID_SCOPE.

terminal

1curl -X POST https://api.paycux.com/v1/billing/organizations \
2  -H "Authorization: Bearer <realm access token>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "projectId": "a1000000-0000-4000-8000-000000000002",
6    "environmentId": "a1000000-0000-4000-8000-000000000003",
7    "realmId": "a1000000-0000-4000-8000-000000000004",
8    "displayName": "Example Robotics"
9  }'
10 
11HTTP 201
12{
13  "billingAccountId": "c2b1a0f9-8e7d-4c6b-9a5f-4e3d2c1b0a99",
14  "kind": "organization",
15  "role": "owner"
16}

Invite a colleague

terminal

1curl -X POST https://api.paycux.com/v1/billing/organizations/c2b1a0f9-8e7d-4c6b-9a5f-4e3d2c1b0a99/invites \
2  -H "Authorization: Bearer <realm access token>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "projectId": "a1000000-0000-4000-8000-000000000002",
6    "environmentId": "a1000000-0000-4000-8000-000000000003",
7    "realmId": "a1000000-0000-4000-8000-000000000004",
8    "email": "colleague@robotics.example",
9    "role": "member"
10  }'
11 
12HTTP 201
13{
14  "inviteId": "e4d3c2b1-a098-4f7e-8d6c-5b4a39281706",
15  "token": "<single-use token, returned once>",
16  "role": "member",
17  "expiresAt": "2026-10-19T09:14:03.220Z"
18}

Accept the invite

terminal

1curl -X POST https://api.paycux.com/v1/billing/invites/accept \
2  -H "Authorization: Bearer <realm access token of the invitee>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "projectId": "a1000000-0000-4000-8000-000000000002",
6    "environmentId": "a1000000-0000-4000-8000-000000000003",
7    "realmId": "a1000000-0000-4000-8000-000000000004",
8    "token": "<single-use token>"
9  }'
10 
11HTTP 200
12{
13  "billingAccountId": "c2b1a0f9-8e7d-4c6b-9a5f-4e3d2c1b0a99",
14  "role": "member",
15  "status": "active"
16}

Register an application from your own tooling

terminal

1curl -X POST https://api.paycux.com/v1/applications \
2  --cookie "__Host-paycux_session=<session cookie>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "projectId": "a1000000-0000-4000-8000-000000000002",
6    "environmentId": "a1000000-0000-4000-8000-000000000003",
7    "name": "Example Robotics",
8    "slug": "example-robotics",
9    "environmentName": "development",
10    "applicationUrl": "https://app.robotics.example/",
11    "identityMode": "external"
12  }'
13 
14HTTP 201
15{
16  "projectId": "a1000000-0000-4000-8000-000000000002",
17  "environmentId": "a1000000-0000-4000-8000-000000000003",
18  "created": true
19}

Verify

Walk the invitation as an end user would, then check what your team can and cannot see.

1Create an organisation with one test identity and confirm GET /v1/billing/accounts lists it with role owner.
2Invite a second address and accept with a token whose e-mail does not match. Expect 403; accept with the right identity and expect status active.
3Reuse the accepted token. Expect 409.
4Open the organisation in the console and confirm e-mail addresses are masked and no token is shown.
5Revoke a pending invite from the console and confirm organization_invite.revoked appears in the audit ledger with via: dashboard.

Connect an applicationRegister a project, its first environment and the setup draft in one step.

Reference

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

Method	Path	What it does
POST	/v1/billing/organizations	Create an organisation; the caller becomes owner (realm token).
GET	/v1/billing/accounts	Accounts and roles of the calling identity (realm token).
POST	/v1/billing/organizations/:billingAccountId/invites	Invite with role member or admin; token returned once (organisation owner/admin).
POST	/v1/billing/invites/accept	Accept an invite with a matching verified e-mail address.
POST	/v1/billing/organizations/:billingAccountId/invites/:inviteId/revoke	Revoke a pending invite (organisation owner/admin).
GET	/v1/billing/organizations/:billingAccountId/members	Members of the organisation; pending invites included for owner/admin.
GET	/v1/environments/:environmentId/organizations	Console: organisations of the environment with member and invite counts (session cookie).
GET	/v1/environments/:environmentId/organizations/:billingAccountId	Console: one organisation with masked members and invites.
POST	/v1/environments/:environmentId/organizations/:billingAccountId/invites/:inviteId/revoke	Console: revoke a pending invite (workspace owner/admin).
POST	/v1/applications	Register a project, its first environment and the setup draft (owner/admin).
GET	/v1/environments/:environmentId/setup	Read the saved setup draft, or { setup: null }.
PUT	/v1/environments/:environmentId/setup	Save the setup draft with expectedRevision (owner/admin).