Reauthorize a connection, or add accounts opened later
Mint a hosted page the end-user opens to re-consent at the
institution, normally keeping the SAME con_ / acc_ / txn_
ids. Two distinct reasons to call it:
- Repair. The connection reports
status = requires_actionand the aggregator needs the end-user to re-enter credentials or re-consent. - Add an account opened after link time. The hosted page
re-opens the institution’s account-selection step, so an
account the end-user opened (or chose not to share) after the
original link can be ticked and starts syncing. This is the
supported way to pick up such an account on a
FINICITYconnection, wherePOST /connections/{connection_id}/refreshonly updates accounts we already hold.
This endpoint is not gated on status. It is equally callable
on an active connection, which is what makes reason 2 work.
Why not just create a new connection?
POST /clients/{client_id}/connections starts a fresh
connection. When the aggregator issues a new underlying login for
the same bank, that mints new con_ / acc_ / txn_ ids for the
same underlying account, so a later delta pull returns transactions
you already have under new ids (your upsert would duplicate
them). Reauthorize repairs the existing connection instead, so the
ids stay stable and a delta re-sync over the overlap window dedupes
cleanly on txn_…. That holds for every response whose source
matches the source segment of the connection_id you sent, which
is the normal case; see “Ids are not always stable” below for the
one response shape where it does not.
What you get back
A hosted reauth_url, a LedgerSync-hosted page the end-user opens
to complete the source-specific flow (Finicity Connect Fix, MX
member reconnect, FDE credential recapture) against the existing
connection. Redirect the user to it, then wait for the
connection.active / connection.failed webhook for the outcome.
The response also carries source: the provider the URL leads to.
See “Ids are not always stable” below.
The URL is a reusable bearer credential
The link is not single-use. It stays valid until
action.expires_at (currently about six days out) and anyone
holding it can open the end-user’s bank-linking session. Deliver it
over a channel you would use for a password reset, do not log it,
and do not embed it in a page that a third party can scrape.
Ids are not always stable
For a bank LedgerSync now serves exclusively through a different provider, the URL we hand back is an add-bank link for that provider rather than a repair link for the connection you named. Today that is Finicity connections at such banks being redirected to MX, and American Express is on that list in production. The list is configuration and can change without an API version bump, so branch on the response rather than on a bank you hard-coded.
When the redirect happens, the end-user’s session creates a new
connection with a new con_ id and new acc_ / txn_ ids, and
the connection you passed is left as it was.
Detect it from the response: source differs from the source
segment of the connection_id you sent. On that branch the
connection.active webhook that follows carries the new
connection’s id, not the one you passed, so key off the Client
rather than the connection: wait for connection.active, then
re-list GET /v3/connections and GET /v3/accounts for that
Client and re-map, rather than expecting the old ids to come back.
Call it because a person asked, not on a timer
Each completed session can share accounts you were not syncing before, and newly shared accounts pull their statement history, which is billable. Trigger this from an explicit user action. Do not schedule it, do not retry it in a loop, and do not mint a second link while the first is still valid.
Available for FINICITY, MX, and FDE. Uploaded-statement
(PDF) data is read-only and has no connection to reauthorize
(400). On MX and FDE you do not need this endpoint to pick up
a newly opened account: a plain refresh discovers it. See
POST /connections/{connection_id}/refresh.
Ownership is enforced server-side: a connection_id that
doesn’t belong to the authenticated customer returns 404.
Empty-body POST
This endpoint takes no request body. Send an explicit
Content-Length: 0 header so the upstream HTTPS load balancer
doesn’t reject the request with 411 Length Required.
Authorizations
Pass your secret key in the Authorization header as a Bearer
token: Authorization: Bearer sk_test_... (sandbox) or
Bearer sk_live_... (production).
Keys are created in the developer portal and the plaintext secret is shown exactly once at creation. Treat them like passwords — never embed them in mobile apps or front-end code.
Path Parameters
Canonical Connection id (con_<SOURCE>_<bankAccountId>) of the
connection to repair, or of the active connection whose
account selection you want the end-user to revisit. The
placeholder UUID from initiate and any con_PDF_* id are
rejected with 400.
"con_FINICITY_41294"
Body
No body. Send Content-Length: 0 so the upstream load
balancer doesn't reject the request with 411.
The body is of type object | null.
Response
A hosted reauthorization URL, plus the source it leads to.
Same source as the connection_id means the existing
connection is repaired and its ids stay stable; a different
one means the URL mints a new connection.
Result of POST /v3/connections/{connection_id}/reauthorize: the
connection id (echoed for correlation), the source the hosted URL
actually leads to, and a reauthorize action carrying that URL.
"con_FINICITY_41294"
The source the hosted URL leads to. Usually the same source as
the connection_id you passed, meaning the existing connection
is repaired in place and its ids stay stable.
When it differs, the URL hands the end-user to a different
provider (today: a Finicity connection at a bank we now serve
exclusively through MX). Completing it creates a new
connection with a new con_ id and new acc_ / txn_ ids
under the same Client; the old connection is not repaired.
Compare this against the source segment of the
connection_id you sent, and if it differs, re-list
GET /v3/connections and GET /v3/accounts for the Client
after the connection.active webhook rather than expecting
the old ids to come back.
FINICITY, MX, FDE, PDF "FINICITY"
