Reference
API reference
This page describes the planned product surface. It is reference material, not a contract: none of the resources below exist in the control-plane API today, and there is no SDK in any language. The implemented routes and their credentials are listed under What exists today.
Not an implemented contract
Every endpoint, object shape and sample key on this page is illustrative. The routes that exist are rendered verbatim from docs/API_CONTRACTS.md at What exists today, and the SDKs page shows how to call them with curl.
Resources
This page is the overview. Each resource has its own page with the full field table, every endpoint, and a request and response example for each of them.
Base URL
The host in the examples, https://api.paycux.com, is the live control-plane API. The resources on this page are not served by it yet, and the environment is chosen by the credential you present, not by the URL.
1https://api.paycux.com
Authentication
This illustrative surface authenticates with a secret key sent as a bearer token. The implemented API has no secret keys: it uses a dashboard session cookie, a realm access token or an agent token, each limited to its own routes. The SDKs page lists the real credentials with examples.
1curl https://api.paycux.com/organizations \2 -H "Authorization: Bearer sk_example_123456789"
In this illustrative model a missing or malformed key returns 401 and a valid key without access to the resource returns 403. See Errors for the full list.
Pagination
List endpoints are cursor paginated. Pass limit (default 10, maximum 100) and use the cursor from list_metadata to walk forwards or backwards. Cursors are opaque — never construct one yourself.
1curl "https://api.paycux.com/users?limit=100&after=user_01HQ8ZK3M4N5P6R7S8T9V0W1X2" \2 -H "Authorization: Bearer sk_example_123456789"34# list_metadata.after is null once you reach the end5{6 "object": "list",7 "data": [ ... ],8 "list_metadata": { "before": null, "after": null }9}
Users
A user is one person. Users exist at the account level and may belong to any number of organizations through memberships.
| GET | /users | List users, filtered by email, organization or creation date |
| POST | /users | Create a user, optionally with a password |
| GET | /users/:id | Retrieve a single user |
| PUT | /users/:id | Update profile fields or verification state |
| DELETE | /users/:id | Delete a user and every session it owns |
| POST | /users/:id/memberships | Add the user to an organization with a role |
1curl -X POST https://api.paycux.com/users \2 -H "Authorization: Bearer sk_example_123456789" \3 -H "Content-Type: application/json" \4 -d '{5 "email": "[email protected]",6 "first_name": "Alan",7 "last_name": "Turing",8 "email_verified": false9 }'
Organizations
An organization is your customer — the tenant that owns a connection, a directory, a role set and a billing relationship.
| GET | /organizations | List organizations in the current environment |
| POST | /organizations | Create an organization with its email domains |
| GET | /organizations/:id | Retrieve a single organization |
| PUT | /organizations/:id | Rename, or change the domains that route to it |
| DELETE | /organizations/:id | Delete an organization and its connections |
| GET | /organizations/:id/memberships | List the people in the organization |
1curl -X POST https://api.paycux.com/organizations \2 -H "Authorization: Bearer sk_example_123456789" \3 -H "Content-Type: application/json" \4 -d '{5 "name": "Foo Corp",6 "domain_data": [{ "domain": "foo-corp.example", "state": "verified" }]7 }'
Connections
A connection is one customer's identity provider. SAML and OIDC differences are normalised, so your code reads the same profile either way.
| GET | /connections | List connections, filtered by organization or state |
| GET | /connections/:id | Retrieve a connection and its current state |
| DELETE | /connections/:id | Remove a connection |
| POST | /portal/generate_link | Create an Organization Setup link for a customer to set one up |
| POST | /sso/token | Exchange an authorization code for a profile and token |
1curl "https://api.paycux.com/connections?organization_id=org_01HQ8ZK3M4N5P6R7S8T9V0W1X2" \2 -H "Authorization: Bearer sk_example_123456789"
Directories
A directory keeps your user list in step with the customer's SCIM endpoint or HR system. You read the result; the reconciliation is ours.
| GET | /directories | List directory connections |
| GET | /directories/:id | Retrieve one directory and its sync state |
| GET | /directory_users | List synced users, filtered by directory or group |
| GET | /directory_users/:id | Retrieve one directory user with raw attributes |
| GET | /directory_groups | List synced groups |
| DELETE | /directories/:id | Disconnect a directory |
1curl "https://api.paycux.com/directory_users?directory=directory_01HQ8ZK3M4N5P6R7S8T9V0W1X2&limit=1" \2 -H "Authorization: Bearer sk_example_123456789"
Roles
Roles are defined per environment and assigned per membership. Permissions travel inside the session, so checking one costs nothing.
| GET | /roles | List roles defined in this environment |
| POST | /roles | Create a role with a slug and permission set |
| PUT | /roles/:id | Change a role's permissions or description |
| DELETE | /roles/:id | Delete a role that is no longer assigned |
| PUT | /memberships/:id | Change the role assigned to one membership |
1curl -X POST https://api.paycux.com/roles \2 -H "Authorization: Bearer sk_example_123456789" \3 -H "Content-Type: application/json" \4 -d '{5 "name": "Billing admin",6 "slug": "billing-admin",7 "permissions": ["invoices:read", "invoices:write", "payment-methods:write"]8 }'
Audit logs
Append-only events with an actor, a target and context. Searchable in the dashboard, exportable on demand, streamable into a customer's own tooling.
| POST | /audit_logs/events | Emit an event from your own application |
| POST | /audit_logs/exports | Start an export for a range and organization |
| GET | /audit_logs/exports/:id | Poll an export and collect the download URL |
| GET | /audit_logs/schemas | List the event actions you have registered |
1curl -X POST https://api.paycux.com/audit_logs/events \2 -H "Authorization: Bearer sk_example_123456789" \3 -H "Content-Type: application/json" \4 -d '{5 "organization_id": "org_01HQ8ZK3M4N5P6R7S8T9V0W1X2",6 "event": {7 "action": "invoice.exported",8 "occurred_at": "2026-06-18T08:14:03.220Z",9 "actor": { "id": "user_01HQ8ZK3M4N5P6R7S8T9V0W1X2", "type": "user", "name": "Alan Turing" },10 "targets": [{ "id": "invoice_2026_06", "type": "invoice" }],11 "context": { "location": "203.0.113.24", "user_agent": "Mozilla/5.0" }12 }13 }'
Webhooks
Endpoints receive signed event deliveries. Manage them from the API when you provision environments programmatically.
| GET | /webhooks | List endpoints registered in this environment |
| POST | /webhooks | Register an endpoint and the events it wants |
| PUT | /webhooks/:id | Change the URL or subscribed event list |
| DELETE | /webhooks/:id | Remove an endpoint |
| GET | /events | Read the event stream directly, for backfills and replays |
1curl -X POST https://api.paycux.com/webhooks \2 -H "Authorization: Bearer sk_example_123456789" \3 -H "Content-Type: application/json" \4 -d '{5 "endpoint_url": "https://api.yourapp.example/paycux/webhook",6 "events": ["dsync.user.created", "dsync.user.deleted", "connection.activated"]7 }'
Looking for what exists?
This reference describes the planned surface, and the changelog on this site is illustrative. The implemented contract is docs/API_CONTRACTS.md, rendered under What exists today; the SDKs page shows how to call it today without a client library.