Connect a merchant login

How a connection works

1. POST /v1/connections with the merchant returns a connect_url: a live window on the merchant's own sign-in page. AgentPay never sees the password.
2. The person opens it and signs in. You call POST /v1/connections/{id}/complete; the login is saved and the connection becomes connected.
3. Pass connection_id to POST /v1/checkout, or leave it out and the run picks the newest connected connection for that merchant by itself.

# 1. start
curl https://api.joomjoo.com/v1/connections \
  -H "Authorization: Bearer $AGENTPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"merchant": "amazon", "user_ref": "user_42"}'

# 2. after the person signed in at connect_url
curl -X POST https://api.joomjoo.com/v1/connections/conn_5d2b.../complete \
  -H "Authorization: Bearer $AGENTPAY_API_KEY"

const conn = await agentpay.connections.create({ merchant: "amazon", user_ref: "user_42" });
// open conn.connect_url for the person, then:
await agentpay.connections.complete(conn.connection_id);

conn = agentpay.connections.create(merchant="amazon", user_ref="user_42")
# open conn["connect_url"] for the person, then:
agentpay.connections.complete(conn["connection_id"])

user_ref is your own reference for the end user the login belongs to. One connection is one person at one merchant; create one per user.

The AgentPay passkey

On merchants that take passkeys (Amazon first), AgentPay adds its own passkey to the person's account the next time a checkout runs on the connection. From then on every checkout signs in by itself, even after the merchant expires the session, and nothing changes in your calls.

A connection reports which layer it runs on:

connected_unmanaged means the passkey works but the merchant shows no identifier AgentPay can use to delete the entry remotely; on disconnect the person removes it themselves.

The one-time password wall

Some merchants ask for the account password once before a passkey can be added. The checkout then stops with needs_login and login_check: "passkey_password". The person is signed in; they type the password at connect_url (AgentPay never stores it) and you start the checkout again on the same connection.

If the person would rather not, skip it. The connection keeps signing in with the saved session and the wall is never shown again for it.

curl -X POST https://api.joomjoo.com/v1/connections/conn_5d2b.../passkey \
  -H "Authorization: Bearer $AGENTPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "skip"}'

Disconnect

DELETE /v1/connections/{id} ends a connection. The AgentPay key is destroyed first, so nothing can sign in with it from that moment; the saved session is deleted; the entry at the merchant is removed when AgentPay can. Poll the connection: passkey_status ends removed, or removed_locally when the person has to remove the entry named AgentPay-... in the merchant's security settings themselves. The call is idempotent.

Reading connections

GET /v1/connections lists every connection on the account, newest first, each with its passkey fields. GET /v1/connections/{id} reads one. Statuses are pending, connected and removed.