Handle a connection re-authentication event

State-system credentials get rotated or revoked outside of SeedLink sometimes. When that happens, the connection stops working until the user re-links.

Subscribe to the event

Code
curl -X POST https://api.seedlink.dev/v1/webhooks \
  -H "Authorization: Bearer sl_at_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/seedlink/webhooks",
    "events": ["connection.requires_reauth"],
    "description": "Connection health"
  }'

Prompt the user to re-link

When the event fires, treat it the same as onboarding a brand-new account: create a link token, open the Connect SDK, and let the user re-enter their credentials.

Code
const connect = SeedlinkConnect.create({
  token: linkToken,
  onSuccess: (publicToken) => {
    // exchange publicToken for a connection_id, same as first-time linking
  },
})
connect.open()

Swap the connection_id in your records

Exchanging the new public_token produces a new connection_id, not a refreshed version of the old one. Update your stored reference to point at it.

Code
curl -X POST https://api.seedlink.dev/v1/link/token/exchange \
  -H "Authorization: Bearer sl_at_..." \
  -H "Content-Type: application/json" \
  -d '{ "public_token": "pt_..." }'

Gotchas

POST /v1/connections/{id}/refresh only re-checks the credentials already stored on that connection. If they were genuinely rotated or revoked, refresh will just confirm they're still invalid. There's no way to update an existing connection's credentials in place, so re-linking is the only fix, and it always produces a new connection_id.