Authentication Reference

Credentials

Flinks uses four credentials. Each serves a different purpose in the authentication flow.

Credential	What it is	How you get it	Lifetime
Secret key	A key that identifies your integration and grants access to Flinks APIs.	Provided by Flinks during integration setup.	Does not expire.
Authorize token	A one-time token that authenticates a single session.	Generated by calling `/GenerateAuthorizeToken` with your secret key.	Single-use. Expires after 15 minutes if unused.
`x-api-key`	A security header required on data endpoints.	Provided by Flinks during integration setup.	Does not expire.
HMAC secret	A shared secret used to verify the authenticity of webhook callbacks from Flinks.	Provided by Flinks during integration setup.	Does not expire.

Toolbox sandbox credentials

Use these shared credentials to test in the Toolbox sandbox environment. They are also listed in Testing Environments.

Credential	Value
Instance	`toolbox`
API Base URL	`https://toolbox-api.private.fin.ag`
Iframe Base URL	`https://toolbox-iframe.private.fin.ag`
customerId	`43387ca6-0391-4c82-857d-70d95f087ecb`
Secret key (for `flinks-auth-key` on `/GenerateAuthorizeToken`)	`c4569c54-e167-4d34-8de6-f4113bc82414`
x-api-key (for data endpoints)	`3d5266a8-b697-48d4-8de6-52e2e2662acc`

These are shared public sandbox credentials for testing. Your production credentials are unique and provided by Flinks during integration setup.

Sandbox iframe setup

When using the sandbox environment with Flinks Connect, you must include demo=true in the iframe URL. This parameter enables the Flinks Capital test institution, which is the only institution available in sandbox.

https://toolbox-iframe.private.fin.ag/v2/?demo=true&authorizeToken={token}

Without demo=true, the Flinks Capital test institution will not appear and you won’t be able to complete the connection flow in sandbox. The demo parameter should only be used in sandbox. Remove it for production. For the full list of iframe parameters, see Flinks Connect Widget Parameters. For sandbox login credentials and test scenarios (MFA, errors, edge cases), see Test Users.

Headers by endpoint

The flinks-auth-key header is used on two endpoints but carries a different value on each.

Endpoint	Header	Value	Required
`/GenerateAuthorizeToken`	`flinks-auth-key`	Your secret key	Yes
`/Authorize`	`flinks-auth-key`	Your authorize token	Yes
Flinks Connect iframe	URL parameter	`authorizeToken={token}`	Yes
`/GetAccountsDetail`	`x-api-key`	Your x-api-key	Yes
`/GetAccountsDetailAsync`	`x-api-key`	Your x-api-key	Yes
`/GetAccountsSummary`	`x-api-key`	Your x-api-key	Yes

Data endpoints (/GetAccountsDetail, /GetAccountsDetailAsync, /GetAccountsSummary, etc.) authenticate using the RequestId returned by /Authorize and the x-api-key header. They do not require the flinks-auth-key header.

Do not confuse the secret key with the authorize token. The secret key generates tokens. The authorize token authenticates sessions. Using the wrong value in the flinks-auth-key header causes 401 errors.

Verify webhook callbacks

When Flinks sends a webhook callback to your endpoint, the request includes an HMAC-SHA256 signature in the flinks-authenticity-key header. Use your HMAC secret to verify that the payload came from Flinks and hasn’t been tampered with. For implementation details and code samples (Python, Node.js), see HMAC Signature Validation.

Authentication flow

Step 1: Generate an authorize token

Call /GenerateAuthorizeToken with your secret key in the flinks-auth-key header. The response contains a one-time authorize token.

Step 2: Authenticate with the authorize token

How you pass the authorize token depends on your integration type:

Flinks Connect: Add authorizeToken={token} as a URL parameter on the iframe URL.
Direct API: Pass the authorize token in the flinks-auth-key header when calling /Authorize.

/Authorize returns a RequestId that you use to call data endpoints.

Step 3: Call data endpoints

Pass the RequestId to data endpoints such as /GetAccountsDetail. No flinks-auth-key header is needed on data endpoints. For the full data retrieval flow after authentication, see Retrieve Account Data.

Handle token expiry in Flinks Connect

The authorize token expires after 15 minutes. The /GenerateAuthorizeToken endpoint does not return a TTL, so your application must handle expiry reactively. If the user does not complete the connection flow within 15 minutes, Flinks Connect emits a JavaScript event:

{ "step": "TOKEN_INVALID" }

When you receive this event, generate a new authorize token and reload the iframe with the updated authorizeToken parameter.

Implementation

Listen for TOKEN_INVALID alongside your other Flinks Connect events:

window.addEventListener("message", function (e) {
  if (e.data && e.data.step === "TOKEN_INVALID") {
    // 1. Call your backend to generate a new authorize token
    //    (your backend calls /GenerateAuthorizeToken with the secret key)
    // 2. Reload the iframe with the new token
    const iframe = document.getElementById("flinks-connect");
    const newUrl = iframe.src.replace(/authorizeToken=[^&]+/, "authorizeToken=" + newToken);
    iframe.src = newUrl;
  }
});

Generate the authorize token from your backend. Do not expose your secret key in frontend code.

Common authentication errors

Error	Flinks Code	Cause
`401`	`ACCESS_DENIED`	Invalid or missing credentials on `/Authorize`.
`401`	`UNAUTHORIZED`	`/GetAccountsDetail` called before completing authorization or MFA.
`401`	`SESSION_EXPIRED`	`RequestId` expired after 8 minutes of inactivity or 30 minutes of data processing, or it was consumed by a completing call.
`401`	`INVALID_REQUEST`	Malformed request body, missing headers, or URL formatting errors (e.g., double slash `//v3`).
`401`	`INVALID_LOGIN`	The `LoginId` passed to `/Authorize` does not exist or is invalid.

/GetAccountsDetail, /GetAccountsDetailAsync, and /GetStatements complete the session and consume the requestId. Later calls with the same requestId return SESSION_EXPIRED. /GetAccountsSummary and Attributes calls do not consume it. In cached mode, a cached requestId is not consumed by cached /GetAccountsDetail.

For the full error code list, see Error Codes. For step-by-step debugging, see Authentication Troubleshooting.

Getting Started

AI

Connect

Enrich

Pay

Webhooks

Upload

Dashboard

Outbound

Security

Support

Credentials

Toolbox sandbox credentials

Sandbox iframe setup

Headers by endpoint

Verify webhook callbacks

Authentication flow

Step 1: Generate an authorize token

Step 2: Authenticate with the authorize token

Step 3: Call data endpoints

Handle token expiry in Flinks Connect

Implementation

Common authentication errors

​Credentials

​Toolbox sandbox credentials

​Sandbox iframe setup

​Headers by endpoint

​Verify webhook callbacks

​Authentication flow

​Step 1: Generate an authorize token

​Step 2: Authenticate with the authorize token

​Step 3: Call data endpoints

​Handle token expiry in Flinks Connect

​Implementation

​Common authentication errors

Credentials

Toolbox sandbox credentials

Sandbox iframe setup

Headers by endpoint

Verify webhook callbacks

Authentication flow

Step 1: Generate an authorize token

Step 2: Authenticate with the authorize token

Step 3: Call data endpoints

Handle token expiry in Flinks Connect

Implementation

Common authentication errors