Getting Started

Three API calls to access your user's financial data.

sequenceDiagram
    participant S as Your Server
    participant A as nrich API
    participant W as Widget
    participant U as User

    S->>A: POST /onetime/access
    A-->>S: {location, id}
    S->>U: Redirect to Widget
    U->>W: Bank selection + SCA
    W-->>U: Redirect to callback with code
    U->>S: code received
    S->>A: POST /auth/token (code)
    A-->>S: access_token (valid 1h)
    S->>A: GET /rest/accounts/ + /rest/transactions
    A-->>S: Financial data (no autosync)

Step 1

Create a Widget link for one-time account access

Step 2

Exchange the authorization code for an access token

Step 3

Fetch accounts and transactions

1. Create the Widget link

POST https://api.finx-s.qwist.cloud/onetime/access

{
  "redirect_uri": "https://my-app.example.com/callback",
  "language": "de",
  "accounts": [
    { "id": "DE89370400440532013000" }
  ],
  "sync_period": 90
}

Parameters:

Parameter	Required	Description
`redirect_uri`	✅	Where the user is returned after completing the flow.
`language`		Widget UI language. Options: `de`, `en`, `es`, `fr`, `ar`. Default: `de`.
`accounts`		Pre-fill the user's IBAN to skip bank selection.
`account_types`		Restrict to specific account types (e.g. `"Giro account"`).
`allow_multi_selection`		`true` (default) lets the user connect multiple accounts.
`sync_period`		Days of transaction history to fetch. Default: `90`.

📘
Improve conversion
If you know the user's IBAN (e.g. from a form they filled in), pass it in accounts. This skips bank selection entirely - the user goes directly to SCA. This is the single highest-impact change you can make to your completion rate.

Response:

{
  "location": "https://widget.qwist.cloud/?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id": "3ca31c37-986a-454e-ad64-8e97143c86bc"
}

Forward the user to location - either as a full redirect or embedded in an iframe overlay. The Widget handles bank selection, login, and SCA.

Read more in the Widget Integration Guide.

🚧
Looking for ongoing access?
This guide covers one-time access only. For continuous account sync, see the Financial Data (ongoing) Implementation Guide.

2. Exchange the authorization code

After the user completes the Widget flow, they are redirected to your redirect_uri with:

Parameter	Description
`code`	Authorization code valid for 1 hour. Present only on success.
`flow_id`	Unique identifier for this flow. Matches the `id` from step 1.
`success`	`true` if the user completed the flow.
`abort`	`true` if the user cancelled.
`state`	Your original `state` value, echoed back for session correlation.

Example callback URL:

https://my-app.example.com/callback
  ?code=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
  &flow_id=3ca31c37-986a-454e-ad64-8e97143c86bc
  &success=true
  &abort=false
  &state=user_42_session_9f3a

🚧
If abort is true
The user cancelled - no code is returned. Show a dismissal state and let the user retry. Do not attempt to exchange a missing code.

Exchange the code for a token

POST https://api.finx-s.qwist.cloud/auth/token

// Request
{
  "grant_type": "authorization_code",
  "code": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "redirect_uri": "https://my-app.example.com/callback"
}

// Response
{
  "access_token": "AoFmNJLDTW8jQtGSJ1iZeeoLiwNZ2ihz3iiCHGpuvE439nppuY...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPt...",
  "scope": "accounts=ro balance=ro transactions=ro"
}

Use the access_token as a Bearer token in the Authorization header for all subsequent requests.

Token	Lifetime	Notes
Authorization code	1 hour	Single use
Access token	1 hour	`Authorization: Bearer {token}`
Refresh token	90 days	Returned but not needed for one-time flows - see below

📘
You do not need to implement token refresh for this flow
Data from a one-time connection is available for 1 hour. After that it is deleted automatically. The refresh_token is returned by the API but serves no purpose here - do not store or use it.

📘
Token storage
Token lengths vary. Allocate at least 2048 bytes per token field in your database - do not use fixed-size columns.

3. Fetch financial data

Use the access_token as a Bearer token. See Fetching Account & Transaction Data for the full endpoint reference.