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

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.

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

Responses

401

Unauthorized — missing or invalid bearer token, company-id header not
set, or the caller is not authorized for the requested scope. Pundit
authorization failures return 401 with an empty body (no 403).

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

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