Reference

API reference

One host, JSON in and JSON out, and objects whose shape does not change with the identity provider behind them. Every endpoint below exists in all six SDKs under the same name.

RESTJSONCursor pagination

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.

UsersPeople, memberships and profile fields OrganizationsTenants and the domains that route to them ConnectionsIdentity providers and the sign-in exchange DirectoriesSynced users, groups and sync state RolesPermission sets and membership assignment Audit LogsEvents, schemas and exports WebhooksEndpoints, signing secrets and rotation EventsThe full event stream, for replay and backfill

Base URL

Every request goes to the same host. The environment is decided by the key you send, not by the URL, which means promoting code from staging to production is a change of secret and nothing else.

1https://api.paycux.com

Authentication

Send your secret key as a bearer token. Keys are server-side only; a request that arrives from a browser origin with a secret key is rejected and logged.

1curl https://api.paycux.com/organizations \
2  -H "Authorization: Bearer sk_example_123456789"

A missing or malformed key returns 401. 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"
3 
4# list_metadata.after is null once you reach the end
5{
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": "alan@foo-corp.example",
6    "first_name": "Alan",
7    "last_name": "Turing",
8    "email_verified": false
9  }'

Full users reference

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  }'

Full organizations reference

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 Admin Portal 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"

Full connections reference

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"

Full directories reference

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  }'

Full roles reference

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  }'

Full audit logs reference

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  }'

Full webhooks reference

Something missing?

The reference tracks the API, and the API changes most weeks. New fields and endpoints are announced in the changelog before they appear here.

Read the changelog Browse the SDKs