Bank key

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:

FieldDescription
idUUID.
user_idFirebase user id of the person who provided the credentials.
companiesPer-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_idIf 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.
typeSTI subclass — bank-specific behavior (e.g. Banking::Cl::BancoDeChile::Key, Banking::ItauKey).
aux_typeAuxiliary classification, used by some banks to differentiate business / personal / corporate flows.
statusLifecycle status (see enum).
rutTax id of the credential's account. Format XXXXXXXX-Y.
emailNotification email registered at the bank.
authorization_methodSecond 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.
prioritySort order when multiple keys share the same company + bank. Higher wins.
bank_errorsRecent errors (auth failures, captcha challenges, scheduled maintenance).
accountsBank accounts visible through this key.
kyc_completedWhether 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.

get/v1/banking/bank_keys

Request

  • Base URL
    https://api.cardda.com
  • Auth
    HTTP bearer

Query parameters

idstring

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

user_idstring

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

type'Banking::BankKey' | 'Banking::ItauKey' | 'Banking::BciKey' | 'Banking::Cl::BancoBice::Key' | 'Banking::Cl::BancoDeChile::Key' | 'Banking::Cl::BancoInternacional::Key' | 'Banking::Cl::BancoSantanderChile::Key' | 'Banking::Cl::BancoScotiabank::Key' | 'Banking::Cl::BancoSecurity::Key' | 'Banking::Cl::Cardda::Key' | 'Banking::Mx::Stp::Key' | 'Banking::Us::Mercury::Key' | 'Banking::Pe::BancoBcp::Key' | 'Banking::VirtualKey'
Example:Banking::Cl::BancoDeChile::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:

aux_typestring

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'pending' | 'approved' | 'declined' | 'preauthorized'
Example:approved

Lifecycle status of the key.

rutstring

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

emailstring

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.

authorization_method'token' | 'digipass' | 'device' | 'multipass' | 'santander_pass' | 'bice_pass' | 'itau_pass'
Example:santander_pass

Second factor pinned on this credential. Almost always null — see the response schema.

prioritystring

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_idstring 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_atstring

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

Parameters

#/paths/~1v1~1banking~1banks/get/parameters/0 (unresolved $ref)
#/paths/~1v1~1banking~1banks/get/parameters/1 (unresolved $ref)
#/paths/~1v1~1banking~1banks/get/parameters/2 (unresolved $ref)
#/paths/~1v1~1banking~1banks/get/parameters/3 (unresolved $ref)

Response

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

Schema[] required(unresolved $ref)

Changes