List bank keys
Changed onReturns a paginated list of bank keys — the credentials Cardda holds on behalf of a company to operate against a bank's online portal.
A bank key is what lets Cardda actually move money: it grants Cardda the rights to list bank accounts, enroll recipients, create transactions, and pull statements/transactions from the bank. Without an approved bank key for a given bank, the rest of the Banking API has no upstream connection.
When you'll use this endpoint
- Show the user "which banks are linked" in your dashboard.
- Detect that a key needs re-authentication (status: declined) — most often because the user changed their bank password.
- Pick the right user_id before issuing a POST /v1/banking/bank_keys/{id}/confirm (re-validation flow). A credential is no longer tied to a single company — see the companies array in the response.
Response structure
Each item is a filtered view of the bank key — sensitive fields (password, secrets, auth_seed, card) are stripped automatically. You get:
| Field | Description |
|---|---|
| id | UUID. |
| user_id | Firebase user id of the person who provided the credentials. |
| companies | Per-company KYC status. A credential can be shared across several companies (razones sociales); each entry carries id, name, identifier (RUT) and kyc_completed. Replaces the removed single-company holder_id. |
| source_key_id | If this key was cloned from a parent key (used for multi-account banks where one set of credentials grants access to multiple accounts), the parent's id. |
| type | STI subclass — bank-specific behavior (e.g. Banking::Cl::BancoDeChile::Key, Banking::ItauKey). |
| aux_type | Auxiliary classification, used by some banks to differentiate business / personal / corporate flows. |
| status | Lifecycle status (see enum). |
| rut | Tax id of the credential's account. Format XXXXXXXX-Y. |
| Notification email registered at the bank. | |
| authorization_method | Second factor pinned on this credential (token, digipass, device, multipass, santander_pass, bice_pass, itau_pass). Almost always null: the method is normally chosen per operation and sent in the authorize/preauthorize body, not stored here. |
| priority | Sort order when multiple keys share the same company + bank. Higher wins. |
| bank_errors | Recent errors (auth failures, captcha challenges, scheduled maintenance). |
| accounts | Bank accounts visible through this key. |
| kyc_completed | Whether KYC was completed for the user that owns the key. |
Common queries
The list is scoped to the credentials owned by the caller (by user_id); the company link now lives in each key's companies array, not a queryable holder_id column.
# Keys for a specific person (the dashboard's pattern)
GET /v1/banking/bank_keys?\
user_id=<firebase_uid>&\
_order=desc&_field=created_at&_start=0&_end=60
# Only declined keys that need re-auth
GET /v1/banking/bank_keys?\
status=declined
# Filter by RUT
GET /v1/banking/bank_keys?\
rut=76123456-7
# Filter by bank type (Banco de Chile only)
GET /v1/banking/bank_keys?\
type=Banking::Cl::BancoDeChile::Key
Security note
Bank-key sensitive fields (password, auth_seed, card, secrets) are never exposed by this endpoint. Cardda exposes them only through a separate, internal-by-default reveal flow that requires a dedicated permission plus a fresh second-factor confirmation; if your integration needs that flow, contact your Cardda account manager.
All operators in Filters are supported on the columns listed below.
Request
- Base URLhttps://api.cardda.com
- AuthHTTP bearer
Query parameters
Filter by bank key UUID. Supports $in for batch lookups.
Firebase user id of the person whose credentials backed the key.
STI subclass — bank-specific behavior. Supply the exact namespaced class name. Banking::Cl::Cardda::Key is the Cardda wallet credential and is by far the most numerous type; Banking::BankKey is the base class, used by credentials with no bank integration behind them. The values in use today are:
Auxiliary classification used by some banks (e.g. business, personal, corporate, enterprise). Set by the bank-specific subclass; consult the team if you need to filter by this for a specific bank.
Lifecycle status of the key.
Tax id of the credential. Format XXXXXXXX-Y (Chilean RUT) or country-specific format.
Notification email at the bank. Accepts a plain email string (email=ops@acme.cl) or a JSON-encoded operator object ({"$regex":"acme.cl$"}) for text search. Schema is type: string (no format: email) so both forms validate; see Filters.
Second factor pinned on this credential. Almost always null — see the response schema.
Sort order when several keys exist for the same company+bank. Defaults to 0. Accepts a plain integer (priority=1) or a JSON-encoded operator object ({"$gte":1}). Schema is type: string so both forms validate; see Filters.
If you cloned a key (multi-account banks), the parent key's UUID. Pull all clones of a parent with source_key_id=<parent_uuid>.
Creation timestamp (UTC ISO-8601). Accepts a single date-time string or a JSON-encoded operator object ({"$gte":"...","$lt":"..."}). Schema is type: string (no format) so both forms validate.
Headers
UUID of the company on whose behalf the request is made. Send it on banking requests to identify the acting company. Note that user-scoped list endpoints (e.g. the recipients/transactions indexes) resolve results across all companies the authenticated user is a member of, rather than strictly from this header. See The company-id header for details on how to obtain a value for this header and the error responses to expect when it is missing or invalid.
Parameters
Response
Paginated list of bank keys (sensitive fields filtered out). Headers include X-Total-Count and Content-Range for offset pagination — see Pagination.
Changes
- info
endpoint added
- info