---
title: "List bank keys"
method: GET
path: "/v1/banking/bank_keys"
tags: ["Bank key"]
---

# List bank keys

`GET /v1/banking/bank_keys`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/banking/bank_keys`
- Auth: HTTP bearer

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

```bash
# 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](https://docs.cardda.com/docs/filters) are supported on the columns listed below.

## Query parameters

- `id` string
- `user_id` string
- `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'
- `aux_type` string
- `status` 'pending' | 'approved' | 'declined' | 'preauthorized'
- `rut` string
- `email` string
- `authorization_method` 'token' | 'digipass' | 'device' | 'multipass' | 'santander_pass' | 'bice_pass' | 'itau_pass'
- `priority` string
- `source_key_id` string, uuid
- `created_at` string

## Headers

- `company-id` string, uuid, required

## 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 `200`

Paginated list of bank keys (sensitive fields filtered out). Headers
include `X-Total-Count` and `Content-Range` for offset pagination —
see [Pagination](https://docs.cardda.com/docs/pagination).

- Schema[] (unresolved $ref)

## Other 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`).

## Changes

- **2026-11-03** `785332193a09`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cardda/apis/banking-api/changes/v1/banking/bank_keys/get.md)

---

[API](https://skmtc.dev/cardda/apis/banking-api.md) - [All operations](https://skmtc.dev/cardda/apis/banking-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/banking-api/revisions/785332193a09?raw)
