Authentication Troubleshooting

​

Common Error Messages

​

”You must provide a valid authorize token” Error

• 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: Use your secret key in the header
• For /Authorize: Use the generated authorize token (not the secret key)

​

Authentication Token Issues

• 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

• 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

​

Token Management

​

Token Usage Rules

• 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 endpoint)
• Generate a new token for each authentication flow

// ❌ 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

# ❌ DON'T USE THESE
--header 'x-api-key: token'        # Wrong header name
--header 'Authorization: token'    # Wrong header name
--header 'Bearer: token'           # Wrong header name

# ✅ CORRECT
--header 'flinks-auth-key: token'  # Correct header name

​

Header Requirements by Endpoint

​

URL Format Issues

​

URL Format Validation

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

• ❌ 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 Configuration

​

Sandbox vs Production Setup

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

• 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

1. Obtain Secret Key: Get from Flinks during integration setup
2. Generate Authorize Token: Call /GenerateAuthorizeToken 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
4. Handle Response: Process successful authentication or error responses

​

Common Integration Mistakes

• Use secret key when calling /GenerateAuthorizeToken
• Use authorize token when calling /Authorize
• Never confuse these two - they serve different purposes

• 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?

1. Check the Error Codes page for specific error code documentation
2. Review the Getting Started guide for complete setup instructions
3. Contact Flinks with specific error details and request context