> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flinks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up Authorization

> Generate and pass an authorize token to securely access Flinks account data.

When completing the authorization process for **both Flinks Connect and direct API connections**, you must pass a valid authorize token to access account data. This adds an extra layer of security by ensuring that only the intended person is accessing the account.

For a summary of all credentials, headers, and which value to pass on each endpoint, see the [Authentication Reference](./authentication-reference).

Complete the steps below to pass us an authorize token each time you authenticate:

### a) Receive a secret key from Flinks

Flinks provides a secret key during the integration process. This is a unique key that identifies you within the system and grants you access to our APIs.

Use your secret key to generate an authorize token. This allows us to confirm your identity and ensure that the correct person is accessing the data.

### b) Generate an authorize token

Call the [/GenerateAuthorizeToken](../../api/authorize/endpoints/generate-authorize-token) endpoint and pass your secret key.

This token can only be used **once** and is active for **30 minutes**. This token expires if it is not used within 30 minutes and you must generate a new one.

### c) Send us an authorize token to successfully authenticate

Those using Flinks Connect will pass the authorize token using a [customization parameter](./flinks-connect/widget#pass-an-authorize-token).

Add the `authorizeToken` customization parameter to your Flinks Connect iframe URL, then pass your authorize token using the format `authorizeToken=123-456-789`. Replace `123-456-789` with your valid token.

**Flinks Connect Example:**

```url URL theme={null}
https://yourinstance-iframe.private.fin.ag/?redirectUrl=flinks.com&authorizeToken=d65f1adb-8ebc-48dc-be8b-20c773ba1565
```

**For Direct API integrations**, pass the authorize token via the `flinks-auth-key` header when calling `/Authorize`:

```bash Direct API Example theme={null}
curl --request POST \
  --url https://yourinstance-api.private.fin.ag/v3/{customerId}/BankingServices/Authorize \
  --header 'Content-Type: application/json' \
  --header 'flinks-auth-key: d65f1adb-8ebc-48dc-be8b-20c773ba1565' \
  --data '{
    "LoginId": "your-login-id",
    "MostRecentCached": true
  }'
```

<Warning>
  **Important Distinctions:**

  * **Secret Key**: Use in `/GenerateAuthorizeToken` header to create tokens
  * **Authorize Token**: Use in `/Authorize` header or Flinks Connect URL parameter
  * **Never confuse these two** - they serve different purposes in the auth flow
</Warning>

## Complete Authentication Flow

### Step-by-Step Process

1. **Obtain Secret Key**: Get your secret key from Flinks during integration setup

2. **Generate Authorize Token**:
   ```bash theme={null}
   curl --request POST \
     --url https://toolbox-api.private.fin.ag/v3/{customerId}/BankingServices/GenerateAuthorizeToken \
     --header 'Content-Type: application/json' \
     --header 'flinks-auth-key: YOUR_SECRET_KEY'
   ```

3. **Use Token Immediately**:
   * **Flinks Connect**: Add `authorizeToken={token}` to iframe URL
   * **Direct API**: Pass token as `flinks-auth-key` header to `/Authorize`

4. **Handle Response**: Process successful authentication or error responses

## Troubleshooting

If you encounter issues while setting up authorization, see our comprehensive [Authentication Troubleshooting](../../api/authorize/troubleshooting) guide for detailed solutions to common problems including header configuration, URL formatting, token management, and environment setup.

## Connect to optional API endpoints to enhance your integration

<Note>
  <p class="h4">Custom integrations only</p>

  This page explains how to set up custom integrations that use a direct API connection. If you are using Flinks Connect, see Set Up Flinks Connect.
</Note>

Complete the following steps to connect with us using a custom API integration that uses OAuth 2.0.

1. Ask your Flinks Representative to whitelist the URLs that your endpoints will be calling, including the redirect URL is step 2A.

2. Call the [/OAuth/Authorize](../../api/authorize/custom/oauth-authorize) endpoint and perform the following tasks:

   * Redirect the end user to their bank’s login screen using the `institution` parameter. Here, they'll enter their login credentials and complete multi-factor authentication (MFA) if required.
   * Provide a URL to redirect the end user back to your website or app using the `redirect_uri` field. If the login is successful, you receive a redirect response containing a `loginId`: `https://{redirect}?loginId={loginId}&state={state}`. If the login is unsuccessful, you receive a redirect response containing an error message: `https://{redirect}?state={state}&error={error}&error_description={error_description}`. For more information on how to make this call, see our [API documentation](../../api/authorize/custom).

3. Call the [/Authorize](../../api/authorize/endpoints/authorize) endpoint and apply the following settings to initiate the authorization flow:

   * Pass the `loginId` that you received in step 2.

   * Make the call in live mode by setting the `MostRecentCached` parameter to `FALSE`.\
     For more information on how to make this call, see our [API documentation](../../api/authorize/endpoints).

   * Set the `save` parameter to `TRUE` to maintain communication with the database (for nightly refreshes, receiving insights, and more).\
     For more information on how to make this call, see our [API documentation](../../api/authorize/endpoints/authorize).

If you receive a `200` response, the end-user is successfully authenticated, and you can now use the Flinks API to retrieve data.