Aggregator connections

Aggregator connections let Matcher pull transaction data from Open-Finance data aggregators (Pluggy, Belvo). You create a connection with a sealed credential, mint a webhook token bound to it, and the aggregator’s webhooks then drive inbound pulls. This guide covers the full lifecycle.

Credentials (clientId/secret) are inbound-only: they are sealed before persistence and are never returned in a response, a log, or an error. Every response on this surface is secret-free by construction. The tenant is always resolved from the JWT, never from the request body.

Create a connection

curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "clientId": "...",
    "secret": "..."
  }'

Field values:

vendor — pluggy or belvo.
configName — unique (tenant-scoped) connection identity; a duplicate is a 409. The webhook token-mint endpoint binds a token to this name.
baseUrl — vendor API base URL, stored as the connection host.
accountRef — opaque vendor account reference (Pluggy itemId, Belvo link id) threaded onto the webhook pull.
clientId / secret — aggregator API credential; sealed and never emitted.

A successful create returns 201 with the secret-free connection descriptor:

{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "baseUrl": "https://api.pluggy.ai",
  "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

List, get, update, delete

# List (cursor-paginated, secret-free)
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections?limit=20" \
  -H "Authorization: Bearer $TOKEN"

# Get by opaque id
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"

Update

Edit an existing connection by id so a mistyped baseUrl is not permanent. The vendor is immutable. The credential is optional: supply both clientId and secret to rotate the sealed credential, or omit both to leave the stored secret intact. Supplying exactly one is a 400.

curl -X PUT "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }'

Delete

curl -X DELETE "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"

Delete soft-deletes the connection (204), freeing its config name for reuse. A non-aggregator connection id returns 404 on any by-id operation — this surface never confirms the existence of a non-aggregator row.

Test a connection

Run a live connectivity check for an existing connection using its already-sealed credential, addressed by (vendor, configName). No credential is supplied or returned.

curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "vendor": "pluggy", "configName": "pluggy-main" }'

{ "vendor": "pluggy", "configName": "pluggy-main", "healthy": true }

A credentials-don’t-work outcome is an expected test result surfaced as "healthy": false with a 200 — not an error. A missing connection is a 404.

Connector types

List the connector types the engine registry has actually registered for this deployment, each tagged with a backend-derived category (database or rest). The list reflects the live registry — only connectors registered at boot appear. It drives the connection form’s type-select.

curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"

{
  "types": [
    { "type": "postgres", "category": "database" },
    { "type": "rest-generic", "category": "rest" }
  ]
}

Aggregator-vendor types (Pluggy/Belvo) are excluded here — they are provisioned through the aggregator-connections surface above.

Mint a webhook token

Mint a webhook token bound to an existing aggregator connection. The raw token and its provider-facing webhook URL are returned once — only the token’s SHA-256 hash is stored.

curl -X POST "https://api.matcher.example.com/v1/discovery/webhooks/tokens" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "connection_config_name": "pluggy-main"
  }'

{
  "token": "<raw-token-shown-once>",
  "webhookUrl": "https://api.matcher.example.com/v1/discovery/webhooks/pluggy/<raw-token>",
  "vendor": "pluggy"
}

Configure the returned webhookUrl in the aggregator’s dashboard. A missing target connection returns 404.

Response codes

Status	Meaning
`200`	Get, list, test, or connector-types returned
`201`	Connection created / token minted
`204`	Connection soft-deleted
`400`	Invalid vendor, partial credential pair, or invalid pagination
`401`	Tenant could not be resolved
`404`	Connection not found (or not an aggregator)
`409`	Connection with that config name already exists

​Create a connection

​List, get, update, delete

​Update

​Delete

​Test a connection

​Connector types

​Mint a webhook token

​Response codes

Create a connection

List, get, update, delete

Update

Delete

Test a connection

Connector types

Mint a webhook token

Response codes