Authentication & keys

Three different things are protected in a Financial Rider integration, and each has its own key. Your backend proves who it is with your application secret. Your customer’s browser talks to the widget with a token of the session’s own. And what our servers push to yours can be encrypted with a key only you hold.

The application secret

Every call carries it:

X-APP-SECRET: <your application secret>

Secrets are issued per application in the console, and an application can hold more than one. That is what makes rotation uneventful: mint the new secret, deploy it, then revoke the old one. Revoking a secret never touches the application, its sessions, its executions or its data. Security & keys is the screen.

When authentication fails, the answer is an HTTP status and a stable detail code — branch on the code, show your own message:

Sandbox or production is decided per session, with settings.sandbox, and a production session needs your application in production and holding its capability — Sandbox and production has what that takes. The base URLs, the error shape and the headers every response carries are the same for every API: Using the API.

The widget signs in on its own

The widget_url that Create Session returns carries a token of its own, valid for that one session. It is what lets your customer’s browser talk to us while they go through the widget — it is not your secret, and nothing in it reaches your application’s other sessions or the API you call from your backend. Treat it as you would the session itself: it goes to the customer it was created for, and to nobody else.

The session key: aes_key

A key you mint, once per session, so that what our servers push to yours is readable only by you. It is optional and recommended: 32 random bytes, Base64-encoded, sent once in settings.aes_key when you create the session.

What follows from it:

• Mint a fresh key for every session. One key per session keeps one session’s payloads from opening another’s.
• Keep it until the session’s last webhook. You need it to decrypt each one, the final event included. Store it server-side, beside the session_id.
• We never give it back. It is not in Get Session Settings, nor in any other answer — losing it means reading that session’s results from the results endpoint instead.

openssl rand -base64 32

import base64, os
aes_key = base64.b64encode(os.urandom(32)).decode()

const aesKey = require('node:crypto').randomBytes(32).toString('base64');

The decryption — strip aes::, split IV, ciphertext and tag, open with AES-256-GCM — is on the Payload Encryption guide, with an interactive sandbox to test it and working code in Node.js, Python and Java.

Nothing to encrypt towards us

Your customer types their credentials into the widget, not into your systems, so a flow’s calls carry nothing for you to encrypt. The application’s inbound key pair — the one Direct Executions uses so that the credentials you send are unreadable on the way — plays no part in integrating a flow.

Without a key, Get Session Results is how the results reach you; with one, the final webhook brings them too. Payload Decryption, on the overview, has the envelope of this flow’s events.

Recurring access: the token key

With recurring access, each bank your customer connects is exchanged for a token, on the Direct Executions API and with your application secret: Exchange a ticket returns a token_id and a token_key.

• token_key is your half of the access, and only yours: we keep the credentials encrypted and a verifier of your key, never the key. Store it as you would a password — encrypted at rest, out of your logs. It is shown once, and replaced on every renewal.
• It is not an encryption key you use. You never encrypt anything with it: it is one input to the derivation that opens the stored credentials, at the moment of a refresh and inside our runtime. Credential Tokenization explains the design, and what losing it means.
• token_id never changes for the life of a connection — not on a refresh, not on a renewal — so it is the key of your list of connections. Your list of connections explains it.