> ## 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.

# Authentication Troubleshooting

This page provides solutions to common authentication issues when working with Flinks authorization endpoints.

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

## Common Error Messages

### "You must provide a valid authorize token" Error

**Problem:** Getting 401 Unauthorized error

**Solutions:**

* Verify your secret key is correct and hasn't expired
* Check the header name is exactly `flinks-auth-key` (not `x-api-key` or `Authorization`)
* For [/GenerateAuthorizeToken](./endpoints/generate-authorize-token): Use your secret key in the header
* For [/Authorize](./endpoints/authorize): Use the generated authorize token (not the secret key)

### Authentication Token Issues

**"You must provide a valid auth key"** (when generating tokens)

* Verify your secret key is correct
* Ensure you're using the secret key provided by Flinks during integration setup
* Check that you're using the correct environment credentials

**"LoginId not found or invalid"** (when authorizing)

* Confirm the LoginId was obtained from a successful Flinks Connect session
* Verify you're using the correct environment (sandbox vs production)
* Check that the LoginId hasn't been deleted via [/DeleteCard](../connect/endpoints/account-linking/delete-card)

## Token Management

### Token Usage Rules

**Important Notes:**

* The generated authorize token is **single-use only**
* Token expires after **30 minutes** if unused
* Use the token immediately in your next API call (either Flinks Connect or [/Authorize](./endpoints/authorize) endpoint)
* Generate a new token for each authentication flow

**Token Reuse Error:**

```javascript theme={null}
// ❌ DON'T DO THIS
const token = 'generated-once';
await callAuthorize(token);
await callAuthorize(token); // This will fail!

// ✅ CORRECT
const token1 = await generateToken();
await callAuthorize(token1);

// Later, for another user/session:
const token2 = await generateToken(); // New token
await callAuthorize(token2);
```

## Header Configuration Issues

### Wrong Header Names

```bash theme={null}
# ❌ DON'T USE THESE
--header 'x-api-key: token'        # Wrong header name
--header 'Authorization: token'    # Wrong header name
--header 'Bearer: token'           # Wrong header name
```

```bash theme={null}
# ✅ CORRECT
--header 'flinks-auth-key: token'  # Correct header name
```

### Header Requirements by Endpoint

| Endpoint                                                        | Header Name       | Header Value                |
| --------------------------------------------------------------- | ----------------- | --------------------------- |
| [/GenerateAuthorizeToken](./endpoints/generate-authorize-token) | `flinks-auth-key` | Your secret key             |
| [/Authorize](./endpoints/authorize) (Direct API)                | `flinks-auth-key` | Generated authorize token   |
| Flinks Connect                                                  | N/A               | Pass token as URL parameter |

<Note>
  **Important:** Do not confuse `flinks-auth-key` with `x-api-key`. Always use `flinks-auth-key` for Flinks authentication.
</Note>

## URL Format Issues

### URL Format Validation

Ensure your URLs follow this exact format:

```
https://{instance}-api.private.fin.ag/v3/{customerId}/BankingServices/{endpoint}
```

**Common mistakes:**

* ❌ `https://toolbox-api.private.fin.ag//v3/...` (double slash)
* ❌ `https://toolbox.api.private.fin.ag/v3/...` (wrong subdomain format)
* ✅ `https://toolbox-api.private.fin.ag/v3/...` (correct)

### Environment-Specific URLs

| Environment     | Instance          | API Base URL                           | Iframe Base URL                           |
| --------------- | ----------------- | -------------------------------------- | ----------------------------------------- |
| Sandbox/Testing | `toolbox`         | `https://toolbox-api.private.fin.ag`   | `https://toolbox-iframe.private.fin.ag`   |
| Production      | Your company name | `https://{company}-api.private.fin.ag` | `https://{company}-iframe.private.fin.ag` |

<Warning>
  Never use production credentials in sandbox or vice versa. Each environment requires its own set of credentials.
</Warning>

## Environment Configuration

### Sandbox vs Production Setup

**Sandbox/Testing Environment:**

* **Instance:** `toolbox`
* **URL:** `https://toolbox-api.private.fin.ag/v3/{customerId}/...`
* **Use test credentials** for generating authorize tokens

**Production Environment:**

* **Instance:** Your company name
* **URL:** `https://{yourcompany}-api.private.fin.ag/v3/{customerId}/...`
* **Use production credentials** provided by Flinks

## Integration Flow Issues

### Authentication Flow Validation

The correct authentication flow:

1. **Obtain Secret Key**: Get from Flinks during integration setup
2. **Generate Authorize Token**: Call [/GenerateAuthorizeToken](./endpoints/generate-authorize-token) with 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](./endpoints/authorize)
4. **Handle Response**: Process successful authentication or error responses

### Common Integration Mistakes

**Wrong Token Type:**

* Use **secret key** when calling [/GenerateAuthorizeToken](./endpoints/generate-authorize-token)
* Use **authorize token** when calling [/Authorize](./endpoints/authorize)
* Never confuse these two - they serve different purposes

**Expired Tokens:**

* Generate new tokens for each authentication session
* Don't cache or reuse tokens across multiple sessions
* Implement token refresh logic in your application

## Need Additional Help?

If these troubleshooting steps don't resolve your issue:

1. Check the [Error Codes](./error-codes) page for specific error code documentation
2. Review the [Getting Started](./getting-started) guide for complete setup instructions
3. [Contact Flinks](../../guides/support/contact-flinks) with specific error details and request context