Agents · Professional Mode

Give agents a safe, explicit operating path inside Payknot.

This page explains how to onboard an AI agent or automation runtime without weakening the payment surface. The goal is easy bootstrap, short-lived runtime identity, and signed high-risk actions.

Open DashboardSee Setup Flow

Recommended policy

Normal host work

Stay in the default event dashboard. No agent controls are shown unless the host opts into Agent Security Mode.

Agent bootstrap

PAT is the onboarding credential because it is easy to issue and easy to store safely in a secret manager.

Payment automation

JWT + Ed25519 signed request is required for the hardened path.

For humans

Browser Session

Use the normal dashboard when a person is creating events and reviewing deposits manually.

Recommended entry point

PAT Bootstrap

Create a Personal Access Token in the dashboard. Agents can use it for host APIs and to bootstrap a hardened runtime session.

For payment automation

Signed Payment Session

Generate an ephemeral Ed25519 keypair, exchange the PAT for a short-lived JWT bound to that public key, then sign sensitive requests.

Agent setup flow

The shortest correct path for a secure agent integration.

STEP 01

Enable Agent Security Mode

Inside the app dashboard, turn on Agent Security Mode. This keeps the normal event dashboard clean for human users and exposes the professional controls only when needed.

STEP 02

Create a PAT

Create a Personal Access Token and copy it once. This is your bootstrap credential, not your permanent high-risk payment credential.

STEP 03

Generate an ephemeral Ed25519 keypair

Your agent runtime should generate its own short-lived keypair locally. Do not ask the host to paste a private key into the dashboard.

STEP 04

Exchange PAT for runtime JWT

Call POST /api/agent/auth/pat with token, session_pubkey, and optional label. The JWT returned is bound to that public key.

STEP 05

Sign payment-impacting requests

For sensitive actions like automated checkout settlement, send Authorization: Bearer <JWT> plus X-Agent-Timestamp and X-Agent-Signature.

STEP 06

Rotate and revoke aggressively

PATs should be revocable. Runtime JWTs are short-lived. Ephemeral session keys should be disposable by design.

Canonical signed request

For high-risk agent actions, Payknot expects the request to be signed using the JWT-bound Ed25519 private key.

POST
/api/agent/checkout/create
<UNIX_TIMESTAMP>
<SHA256_HEX_OF_RAW_BODY>

Headers:

Authorization: Bearer <agent_jwt>
X-Agent-Timestamp: <unix_seconds>
X-Agent-Signature: <base64_ed25519_signature>

Use agents deliberately, not implicitly.

Payknot now keeps the default dashboard clean for normal hosts and moves professional agent controls behind an explicit Agent Security Mode toggle. That separation is intentional because payment automation deserves a sharper security boundary.

Open Agent Security ModeRead Skill.md