Credential Tokenization

Refreshing somebody’s data every month should not mean keeping their bank password in your database. Tokenization moves that problem off your side without moving it wholly onto ours: the credentials are stored encrypted by the platform, under a key that only exists while you present the token you hold.

Neither half is enough on its own. That is the whole design, and it is worth understanding before you decide whether to use it — because it also decides what happens when something goes wrong.

The two halves

How the encryption works

This is the part that makes the split real rather than a promise.

What that means in practice

Losing the key is final, and that is deliberate

There is no recovery path, no support ticket and no override. If the token key is lost, the stored credentials become bytes nobody can open — including us.

Final for the key — not for the connection. Losing the key loses the ability to refresh, nothing else: start a new session for the same customer_id, have your customer connect the same account, and exchange its ticket. The answer carries the same token_id with a new key, so the entry you keep for that connection — and everything you hang off it — goes on working. That is the only way back, and it involves your customer, because it involves their password. How to build it.

What a token can do, and for how long

A token is not a general-purpose credential. Its scope is fixed at the exchange, and a run can narrow it but never widen it:

It expires 90 days after the exchange, and using it does not extend that. When the date arrives, the stored credentials are deleted. Track it and renew the connection before it lapses — a quarterly job that never renews works for three months and then fails for everybody at once.

A token can also be locked by the source: if the institution rejects the stored credentials or blocks the account, the token stops running and says so. Retrying does not help and can make it worse — institutions count failed attempts. That is a conversation with your customer, and it ends with them connecting the account again.

One token per connection. A connection is your application, one source, one customer_id and one account at that source. Exchanging a ticket for a connection that already has a token renews it — the same token_id, a new key, the new run’s scope and expiry, renewed: true — instead of minting a second one. A renewal revokes nothing: token_id never changes for the life of a connection. Managing your customers’ connections turns that into a list you can show.

Managing your customers’ connections

A practical guide: what to keep on your side, and how to turn it into the screen your customer uses — BBVA, connected · Santander, needs your attention — with connect, reconnect and remove.

The rule underneath is one sentence: a connection is one row, and token_id is its key. It is the one field that never changes for the life of a connection — not on a refresh, not on a lock, not on a reconnection.

What to keep, one row per connection

Never keep the password — you never had it, which is the point — nor the ticket once it is exchanged.

Connect, reconnect, remove

What each row shows

The whole rule in code

Every Exchange a ticket answer is an upsert keyed by token_id:

def keep(rows: dict, exchanged: dict) -> str:
    """`rows` maps token_id -> what you keep for that connection. Returns what happened."""
    token, context = exchanged["token"], exchanged["context"]
    rows[token["token_id"]] = {
        "token_key": encrypt(token["token_key"]),   # yours to protect: it is never shown again
        "customer_id": context["customer_id"],
        "engine_reference": context["engine_reference"],
        "source_execution_id": context["source_execution_id"],
    }
    return "reconnected" if exchanged["renewed"] else "connected"

There is nothing to deduplicate and nothing to compare yourself — not locking_hash, not the bank’s name: the exchange has already decided whether this is a connection you have. An exchange that answers 409 overlapped another of the same ticket — a retry: wait for that one, or retry after its Retry-After.

If you lose a key

You lose the refresh of that connection, not the connection. Start a new session for the row’s customer_id and have your customer connect the same account: the exchange answers the row’s own token_id with a new key, and the row works again — keep the new key somewhere you cannot lose it this time. Under a different customer_id, the same account would be another connection, and the old row would stay without a key.

Revoking

Revocation is immediate and irreversible: no execution can use the token afterwards, and the stored credentials are marked for deletion. Call it when a customer withdraws consent, closes their account with you, or asks you to stop — and after any suspicion that your half leaked.

Where to do all of this