Agent Connect

Use agent connect when an agent instance needs to attach itself to a signed-in ChatBlocks account. This is a one-time linking flow, not a replacement for API keys.

What this is for

• Attach an agent instance to a user account
• Hand off identity from the signed-in web app to the agent
• Confirm the link by polling from the agent side

Use API keys for normal authenticated API requests after the account is linked.

Flow

1. Open Settings and generate a one-time token
2. Paste that token into your agent
3. Open the generated connect link while signed in
4. The web app calls POST /api/connect/claim and attaches the token to your account
5. Your agent polls POST /api/agent/token until it receives ok: true

Web claim endpoint

The signed-in browser claims the token with session auth:

curl -X POST https://chatblocks.app/api/connect/claim \
  -H "Content-Type: application/json" \
  -b "your_session_cookie" \
  -d '{"token":"YOUR_CONNECT_TOKEN"}'

Successful response:

{
  "ok": true
}

Notes:

• The request requires a signed-in browser session
• Tokens shorter than 8 characters are rejected
• If a token has not been seen before, ChatBlocks creates the record and immediately claims it for the current user
• A token already claimed by another user returns an error

Agent polling endpoint

Your agent can poll until the token is claimed:

curl -X POST https://chatblocks.app/api/agent/token \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_CONNECT_TOKEN"}'

Before claim:

{
  "ok": false,
  "error": "Token not claimed"
}

After claim:

{
  "ok": true,
  "userId": "user_123",
  "claimedAt": "2026-03-06T18:00:00.000Z"
}

Security notes

• Treat the token like a password
• Generate a new token if one is exposed
• Use the connect token only for account linking
• Use API keys for normal programmatic access after linking