Integrate Abuse Checks

Before you begin

• A project with an environment whose customer identity setup is ready. End-user calls carry a realm access token issued by that environment's realm.
• A way to mint an Idempotency-Key per logical action in your application. A UUID or a stable key such as <order id>-<step> both work; keys are 8 to 128 characters.
• A retry policy that honours Retry-After. Retrying faster than the header says only lengthens the wait.
• If you operate the API yourself, the proxy topology in PAYCUX_TRUSTED_PROXIES. Without it only identities are counted.

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.

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 API address and the scope it calls with. The realm id is shown on the environment's Authentication page once setup is ready; the billing account id comes from the end-user billing routes.

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:

1. 1Open the environment's Authentication page and complete identity setup. The realm Paycux provisions has brute-force protection switched on from the first sign-in.
2. 2Open Settings and invite your colleagues from Members. The invitation budget applies here; a 429 means wait, not that the invitation failed for good.
3. 3Open the environment's Usage page after your first events. A refused request never appears there, because a 429 writes nothing.
4. 4Open Billing to see the plan limits on projects, connections, members and usage events. Those answer 402, not 429, and are separate from damping.

Implement

Three habits cover everything: send an Idempotency-Key on every usage event and checkout, treat 429 as a pause rather than an error, and branch on the usage decision rather than on the HTTP status.

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

1# Identical request, same Idempotency-Key
2 
3# 200 OK
4{
5  "allowed": true,
6  "reason": "WITHIN_LIMIT",
7  "consumed": 12,
8  "limit": 100,
9  "eventId": "<event id>",
10  "duplicate": true
11}

1HTTP/1.1 429 Too Many Requests
2retry-after: 3
3content-type: application/json
4 
5{ "error": "RATE_LIMITED", "message": "Too many requests; retry after 3s" }

1curl -X POST https://api.paycux.com/v1/workspace/members/invites \
2  --cookie "__Host-paycux_session=<session cookie>" \
3  -H "Content-Type: application/json" \
4  -d '{ "email": "[email protected]", "role": "developer" }'
5 
6# 201 Created
7{
8  "invite": {
9    "id": "<invite id>",
10    "email": "[email protected]",
11    "role": "developer",
12    "status": "pending",
13    "invitedByMemberId": "<member id>",
14    "expiresAt": "2026-10-20T09:00:00.000Z",
15    "createdAt": "2026-10-13T09:00:00.000Z"
16  },
17  "token": "<invite token>",
18  "acceptUrl": "https://paycux.com/auth/start?mode=login&invite=<invite token>",
19  "emailQueued": true
20}
21 
22# Budget spent: 429 RATE_LIMITED with Retry-After
23# Plan limit reached: 402 PLAN_LIMIT_EXCEEDED with featureKey, limit and current

1curl -X POST https://api.paycux.com/v1/billing/checkout-sessions \
2  -H "Authorization: Bearer <realm access token>" \
3  -H "Idempotency-Key: checkout-<billing account id>-pro-0001" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "projectId": "<project id>",
7    "environmentId": "<environment id>",
8    "realmId": "<realm id>",
9    "billingAccountId": "<billing account id>",
10    "planKey": "pro",
11    "successUrl": "https://app.example.com/billing/success",
12    "cancelUrl": "https://app.example.com/billing/cancel"
13  }'
14 
15# 201 Created
16{
17  "provider": "paddle",
18  "mode": "sandbox",
19  "checkoutUrl": "https://paycux.com/checkout/customer/<session token>",
20  "expiresAt": "2026-10-13T09:30:00.000Z",
21  "billingAccountId": "<billing account id>",
22  "planKey": "pro"
23}

Verify

The interesting test is the negative one. Confirm that a normal client is never refused before you confirm that a runaway one is.

1. 1Send a usage event, then send it again with the same Idempotency-Key. The second answer carries duplicate: true and the same eventId, and the Usage page shows one event.
2. 2Send a usage event without an Idempotency-Key and confirm 400 INVALID_INPUT with nothing recorded.
3. 3Run a tight loop of usage events for one identity and confirm the first refusal is 429 RATE_LIMITED with a Retry-After header. Wait that long, retry with the same key and confirm it is processed.
4. 4Invite addresses in a loop from one workspace and confirm the loop ends in 429 rather than a queue of e-mails. Revoke the test invitations afterwards.
5. 5Fail a sign-in on the environment's hosted sign-in page repeatedly and confirm the realm starts refusing attempts temporarily. A correct password after the wait signs in.

Reference

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

Next steps