List bank keys

get

https://api.cardda.com/v1/banking/bank_keys

Returns 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 a valid active 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: invalid) — most often because the user changed their bank password.
Pick the right holder_id / user_id combination before issuing a POST /v1/banking/bank_keys/{id}/confirm (re-validation flow).

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.
`holder_id`	UUID of the company that owns this credential.
`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::Security::BankKey`, `Banking::Santander::BankKey`).
`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`.
`email`	Notification email registered at the bank.
`authorization_method`	What the user has to provide to authorize transactions (`coordinate_card`, `digipass`, `sms`, `mobile_app`, `signature`).
`priority`	Sort order when multiple keys share the same `holder_id` + `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

# Keys for a specific person and company (the dashboard's pattern)
GET /v1/banking/bank_keys?\
  holder_id=<company_uuid>&\
  user_id=<firebase_uid>&\
  _order=desc&_field=created_at&_start=0&_end=60

# Only invalid keys that need re-auth
GET /v1/banking/bank_keys?\
  status=invalid&\
  holder_id=<company_uuid>

# Filter by RUT
GET /v1/banking/bank_keys?\
  rut=76123456-7&holder_id=<company_uuid>

# Filter by bank type (Banco de Chile only)
GET /v1/banking/bank_keys?\
  type=Banking::BancoDeChile::BankKey&\
  holder_id=<company_uuid>

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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

_start

integer

≥ 0

If all the transactions where in an array, this would represent the index of the first item returned in the response

_end

integer

≥ 0

If all the transactions where in an array, this would represent the index of the last item returned in the response

_order

string

enum

The order method, which can be ascending or descending

Allowed:

_field

string

The field used to sort, the example illustrates a response that would be sorted by the creation date

string

Filter by bank key UUID. Supports $in for batch lookups.

holder_id

uuid

UUID of the company that owns the key. The dashboard always pins the active company here and pairs it with user_id.

user_id

string

Firebase user id of the person whose credentials backed the key.

type

string

enum

STI subclass — bank-specific behavior. Supply the exact namespaced class name. The frequent values today are:

aux_type

string

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.

status

string

enum

Lifecycle status of the key.

Allowed:

rut

string

Tax id of the credential. Format XXXXXXXX-Y (Chilean RUT) or country-specific format.

string

Notification email at the bank. Accepts a plain email string ([email protected]) 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.

authorization_method

string

enum

What the user has to provide to authorize transactions backed by this key.

Allowed:

priority

string

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.

source_key_id

uuid

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>.

created_at

string

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

company-id

uuid

required

UUID of the company on whose behalf the request is made. Required for every banking endpoint. 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.

Responses

401

Unauthorized — missing or invalid bearer token, or company-id header not set.

403

Forbidden — user is not a member of the company referenced by company-id.

200Paginated list of bank keys (sensitive fields filtered out). Headers include X-Total-Count and Content-Range for offset pagination — see Pagination.