Integrate Agent Access

Before you begin

• A workspace with a project. Agent connections are minted for the project's canonical development environment, which the console creates with the project.
• A member with the owner, admin or developer role. Other roles cannot mint or revoke connections.
• A way to hand the agent its token without writing it to disk or an environment variable. The token is shown once in the mint response and expires minutes later.
• Nothing from your provider accounts. The agent never needs a Stripe or Paddle key, and no route gives it one.

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 agent needs the API address and the project id; the environment is always development. The planned paycux CLI and paycux-mcp server read the address from PAYCUX_API_URL and the token from a protected pipe named by PAYCUX_AGENT_TOKEN_FD, so keeping the address under that name avoids a rename when they ship.

1PAYCUX_API_URL=https://api.paycux.com
2PAYCUX_PROJECT_ID=<project id>

Then, in the dashboard:

1. 1Sign in and open the project the agent will work on. Its development environment is the only one a connection can bind to; the mint call answers 404 NOT_FOUND when the project has no environment named development.
2. 2Note the project id from the project page. The mint body and the activation body both carry it.
3. 3There is no console page for agent connections yet. Mint and revoke are API calls made with your session cookie, shown below.
4. 4Keep provider credentials where they are, on the environment's Connections page. The agent reads a public contract, not the connection.

Implement

Four calls. Mint with the session cookie, activate once with the token, read the contract with the token, revoke with the session cookie. Verification runs are described at the end as planned. A paycux CLI (link, contract pull, verify start) and a paycux-mcp server (paycux_get_contract, paycux_start_verification, paycux_get_verification) that wrap these routes exist in the codebase as private workspace packages; they are not distributed, so this page shows the routes themselves and the planned clients only by name.

1curl -X POST https://api.paycux.com/v1/agent/connections \
2  --cookie "__Host-paycux_session=<session cookie>" \
3  -H "Content-Type: application/json" \
4  -d '{ "projectId": "<project id>", "capabilities": ["contract:read"] }'
5 
6# 201 Created
7{
8  "token": "pcx_<connection id>.<secret>",
9  "projectId": "<project id>",
10  "environmentId": "<development environment id>",
11  "expiresAt": "2026-10-13T09:05:00.000Z",
12  "capabilities": ["contract:read"]
13}
14 
15# 403 FORBIDDEN for billing or viewer roles
16# 404 NOT_FOUND when the project has no development environment

1curl -X POST https://api.paycux.com/v1/agent/activate \
2  -H "Authorization: Bearer <agent token>" \
3  -H "Content-Type: application/json" \
4  -d '{ "projectId": "<project id>", "environment": "development" }'
5 
6# 200 OK
7{
8  "projectId": "<project id>",
9  "environmentId": "<development environment id>",
10  "environment": "development",
11  "expiresAt": "2026-10-13T09:05:00.000Z",
12  "capabilities": ["contract:read"]
13}
14 
15# Again: 409 AGENT_ALREADY_ACTIVATED
16# Another project id: 403 AGENT_SCOPE_DENIED
17# Any environment but development: 403 AGENT_ENVIRONMENT_DENIED
18# After expiry: 401 AGENT_TOKEN_EXPIRED

1curl https://api.paycux.com/v1/agent/contract \
2  -H "Authorization: Bearer <agent token>"
3 
4# 200 OK
5{
6  "projectId": "<project id>",
7  "environmentId": "<development environment id>",
8  "environment": "development",
9  "sourceSha": "<commit sha>",
10  "integrationInstructions": ["<public instruction>"],
11  "hostedUrls": { "checkout": "<https url>", "portal": "<https url>" },
12  "publicConfig": { "authMode": "paycux", "usageEndpoint": "https://api.paycux.com/v1/usage/events" }
13}
14 
15# 403 AGENT_CAPABILITY_DENIED when the connection lacks contract:read
16# 401 AGENT_TOKEN_INACTIVE before activation

1curl -X POST https://api.paycux.com/v1/agent/connections/<connection id>/revoke \
2  --cookie "__Host-paycux_session=<session cookie>"
3 
4# 204 No Content
5# The token now answers 401 AGENT_TOKEN_REVOKED

1curl -X POST https://api.paycux.com/v1/agent/verifications \
2  -H "Authorization: Bearer <agent token>"
3 
4# 503 Service Unavailable
5# { "error": "VERIFICATION_NOT_CONFIGURED", ... }

Verify

Five checks prove the scope is doing its job, and the last one confirms the boundary of this release:

1. 1Mint a connection and check that expiresAt is a few minutes out. Activate it; the response repeats the scope and capabilities.
2. 2Activate the same token again and confirm 409 AGENT_ALREADY_ACTIVATED. Activate a fresh token with another project's id and confirm 403 AGENT_SCOPE_DENIED.
3. 3Read the contract and confirm it carries no secret-like values; the schema refuses to serve any.
4. 4Revoke the connection from the console session and retry the contract call. It must answer 401 AGENT_TOKEN_REVOKED at once, not at expiry.
5. 5Post to /v1/agent/verifications with a live token and confirm 503 VERIFICATION_NOT_CONFIGURED. Hosted verification runs are planned.

Reference

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

Next steps