SDKs

No SDK today

There is no npm, PyPI, Go module, RubyGems, Composer, Maven or NuGet package for Paycux. A dependency named paycux in any registry is not ours. Integrate with the HTTP client your runtime already has.

• Every implemented route and the credential it requires is listed under What exists today, rendered verbatim from docs/API_CONTRACTS.md
• Every request and response body is JSON; validation failures return 400 with the error code INVALID_INPUT
• The control-plane host is https://api.paycux.com; the examples below call it directly

The three credentials

Paycux has no secret API keys. Each route family accepts exactly one kind of credential, and they are never mixed: a dashboard session can never satisfy an end-user route, and a realm token cannot read workspace data.

Dashboard session

The console signs you in with OpenID Connect and stores the result in a host-bound, HttpOnly cookie. That cookie is the credential for workspace routes: projects, environments, members, catalog and workspace billing. It belongs to the browser session; there is no API key for workspace administration today.

1curl https://api.paycux.com/v1/auth/session \
2  -H "Cookie: __Host-paycux_session=<value from your signed-in browser>"
3 
4# 200
5{ "workspaceId": "…", "actorId": "…", "role": "owner" }

Realm access token

Your application's users authenticate against the identity realm Paycux provisions for each environment. Send that realm's access token as a bearer token. Paycux verifies it against the realm's published keys and audience, requires a verified e-mail and maps the subject to a realm-scoped identity, created on first use.

1curl -X POST https://api.paycux.com/v1/usage/events \
2  -H "Authorization: Bearer $REALM_ACCESS_TOKEN" \
3  -H "Idempotency-Key: usage-2026-10-13-000001" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "projectId": "<project uuid>",
7    "environmentId": "<environment uuid>",
8    "realmId": "<realm uuid>",
9    "billingAccountId": "<billing account uuid>",
10    "meterKey": "api_calls",
11    "quantity": 1,
12    "occurredAt": "2026-10-13T09:00:00Z"
13  }'
14 
15# 200 UsageDecision
16{
17  "allowed": true,
18  "reason": "WITHIN_LIMIT",
19  "consumed": 1,
20  "limit": 1000,
21  "eventId": "…",
22  "duplicate": false
23}

• The body scope (projectId, environmentId, realmId) must match the credential, and the identity must be an active member of the billing account
• Idempotency-Key is 8 to 128 characters; repeating a key returns the same decision with duplicate: true
• Checkout, portal and cancellation sessions use the same credential under /v1/billing and are created on your own Stripe or Paddle account

Agent token

An agent connection binds a CLI or coding agent to one project's development environment. The token is short-lived, starts with pcx_ and carries only the capabilities it was issued with: read the integration contract, start a verification run, read a verification run. The paycux CLI and the paycux-mcp server read it from a protected pipe, never from a flag or a file.

1curl https://api.paycux.com/v1/agent/contract \
2  -H "Authorization: Bearer $PAYCUX_AGENT_TOKEN"
3 
4# 200 — the project's public integration contract; no provider secrets

Conventions

Four rules hold across every implemented route.