Skip to main content
POST
/
v3
/
{customerId}
/
BankingServices
/
Authorize
Authorize
curl --request POST \
  --url https://{instance}-api.private.fin.ag/v3/{customerId}/BankingServices/Authorize \
  --header 'Content-Type: application/json' \
  --data '
{
  "Username": "greatday",
  "Password": "everyday",
  "Institution": "FlinksCapital",
  "Language": "en",
  "MostRecentCached": false,
  "Save": true
}
'
{
  "HttpStatusCode": 200,
  "Links": [
    {
      "rel": "AccountsDetail",
      "href": "/GetAccountsDetail",
      "example": null
    },
    {
      "rel": "AccountsSummary",
      "href": "/GetAccountsSummary",
      "example": null
    },
    {
      "rel": "Statements",
      "href": "/GetStatements",
      "example": null
    }
  ],
  "InstitutionName": "FlinksCapital",
  "Login": {
    "Username": "Greatday",
    "IsScheduledRefresh": false,
    "LastRefresh": "2026-01-21T20:47:47.145999",
    "Type": "Personal",
    "Id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "InstitutionId": 14,
  "Institution": "FlinksCapital",
  "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

​
/Authorize Endpoint

The /Authorize endpoint is used to initiate a new session and retrieve cached banking data for a specific user.

​
Purpose

  • Starts a new session by generating a requestId
  • Returns the most recent data aggregation for a specific card (user account)
  • Enables access to other data endpoints like /GetAccountsSummary, /GetAccountsDetailand /GetStatements

Flinks Connect Widget Integration

Flinks Connect Widget handles:
  • User banking authentication
  • Multi-Factor Authentication (MFA)
Once authentication is successful, Flinks Connect Widget returns a loginId via URL or event.
In order to successfully retrieve the cached data, you will need to specify the following parameters in your call to /Authorize: 
{
  "LoginId": "{LoginId}",
  "MostRecentCached": true
}

​
Successful Response

A successful call returns:
  • HTTP status code 200
  • A list of available data endpoints
  • Metadata including:
    • Login details (e.g., username, refresh status, type)
    • Institution name
    • RequestId (used for subsequent data calls)
{
  "Links": [
    {
      "rel": "AccountsDetail",
      "href": "/GetAccountsDetail",
      "example": null
    },
    {
      "rel": "AccountsSummary",
      "href": "/GetAccountsSummary",
      "example": null
    },
    {
      "rel": "Statements",
      "href": "/GetStatements",
      "example": null
    }
  ],
  "HttpStatusCode": 200,
  "Login": {
    "Username": "Greatday",
    "IsScheduledRefresh": false,
    "LastRefresh": "2020-04-15T22:46:03.1690585",
    "Type": "Personal",
    "Id": "b0debb48-f9f1-46c6-80a4-08d7dd88d478"
  },
  "InstitutionId": "14",
  "Institution": "FlinksCapital",
  "RequestId": "006fd2f3-055b-4ef6-a9fc-c1261cd76ec6"
}
Once this step is reached, it means that your session was successfully opened, and the received RequestId can be used to make calls to other data retrieval endpoints.

Note on the HTTP status code

🕒 LastRefresh is in UTC.

​
LoginId Notes

  • A LoginId is tied to a specific institution, username, and language.
  • It remains the same even if the password changes.
  • It is unique to each instance (e.g., sandbox vs. production).

Remember for each loginId

Keep track of each LoginId for future use or deletion. Flinks retains data indefinitely unless you call /DeleteCard.

​
Multi-Factor Authentication (MFA)

If the response returns HTTP 203, MFA is required. You must:
  • Collect the user’s answers to security questions.
  • Call /Authorize again with the RequestId and SecurityResponses parameters.

Headers

​
flinks-auth-key
string

The Bearer Token (API secret key).

​
Content-Type
string
default:application/json

Content type of the request.

Example:

"application/json"

​
Accept
string
default:application/json

Acceptable response media type.

Example:

"application/json"

Path Parameters

​
customerId
string
default:43387ca6-0391-4c82-857d-70d95f087ecb
required

Unique GUID provided by Flinks that grants you access to the environment specified in the instance field. By default, the value is the key for the toolbox environment.

Example:

"43387ca6-0391-4c82-857d-70d95f087ecb"

Body

application/json
​
Username
string
default:greatday

Username used to connect to the financial institution

Example:

"greatday"

​
Password
string
default:everyday

Password used to connect to the financial institution

Example:

"everyday"

​
Institution
string
default:FlinksCapital

Unique identifier of the financial institution

Example:

"FlinksCapital"

​
Language
string
default:en

Preferred language for the connection process (en | fr)

Example:

"en"

​
LoginId
string

Access token associated with a customer account

​
MostRecentCached
boolean
default:false

true = cached mode, false = live mode

Example:

false

​
Save
boolean
default:true

If set to true, all collected data and credentials will be saved after the request is completed.

Example:

true

​
Tag
string

Custom string to attach to a specific request.

​
RequestId
string<uuid>

Required for MFA. Pass the RequestId received in the 203 response.

​
SecurityResponses
object

Pass this parameter if you received a 203 response from the /Authorize endpoint and are calling it a second time to complete MFA questions. This parameter contains the user's responses to the MFA questions, where keys are the prompts and values are arrays of answers.

Response

Authorization successful - Session opened and RequestId can be used for subsequent data calls

​
HttpStatusCode
integer

HTTP status code

Example:

200

​
Links
object[]

List of available data endpoints

Example:
[
  {
    "rel": "AccountsDetail",
    "href": "/GetAccountsDetail",
    "example": null
  },
  {
    "rel": "AccountsSummary",
    "href": "/GetAccountsSummary",
    "example": null
  },
  {
    "rel": "Statements",
    "href": "/GetStatements",
    "example": null
  }
]
​
InstitutionName
string

Name of the financial institution

Example:

"FlinksCapital"

​
Login
object

End user's technical login information

Example:
{
  "Username": "Greatday",
  "IsScheduledRefresh": false,
  "LastRefresh": "2026-01-21T20:47:47.145999",
  "Type": "Personal",
  "Id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
​
InstitutionId
integer

Unique identifier of the financial institution

Example:

14

​
Institution
string

Name of the financial institution

Example:

"FlinksCapital"

​
RequestId
string<uuid>

Unique request identifier used for subsequent data calls

Example:

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"