Overview 💥
The Gradient + Liongard integration allows you to sync Liongard data directly into Gradient Synthesize for billing hygiene, normalized configuration data, and PSA reconciliation.
During setup, you may encounter authentication or connectivity issues. This guide outlines the most common causes, resolutions, and best practices to ensure a successful connection.
Why Issues Occur? 🤔
Connection failures typically happen due to one of the following:
Category | Description |
Incorrect Liongard Instance | The instance name entered into Gradient does not match your Liongard subdomain (e.g., |
Invalid / Expired API Token | The Liongard Access Key or Secret was revoked, expired, or improperly copied. |
Permission Issues | The API token was created from an account lacking required permissions in Liongard. |
Copy/Paste Errors | Extra spaces, missing characters, or line breaks cause authentication failure. |
Connectivity Issues | Temporary downtime or regional routing issues between Gradient and Liongard. |
Troubleshooting Guide 🧑🏫
Step 1: Generate a New Liongard API Token
Before connecting to Gradient, ensure your token is valid and active.
How to Generate a Token
Log into Liongard.
Click your username in the upper right corner.
Select Account Settings.
Go to Access Tokens.
Click Generate New Token > Liongard API Token
Copy both:
Access Key ID
Access Key Secret
Store both securely in a password manager.
⚠ Important: The Secret is shown only once. Liongard cannot reveal it again.
Step 2: Connect Liongard to Gradient
Log into Gradient Synthesize.
Navigate to Integrations.
Locate the Liongard integration card.
Click Connect.
Enter:
Instance
Example: If your Liongard URL is
https://us1.app.liongard.com→ Instance = us1Access Key ID
Access Key Secret
Click Authenticate.
Once validated, complete the Liongard Integration Wizard.
Common Issues & How to Fix Them 👨💻
1️⃣ Incorrect Instance Name
Symptoms:
Authentication fails immediately
Error indicates "invalid instance" or "unable to connect"
How to Validate Your Instance
Check the beginning of your Liongard URL:
URL | Instance |
|
|
|
|
|
|
Fix: Enter the exact subdomain as the Instance in Gradient.
2️⃣ Expired or Revoked API Token
Symptoms:
Authentication previously worked but suddenly fails
Token not recognized by Liongard
Fix:
Generate a new API token (Step 1)
Update Gradient with new credentials
3️⃣ Insufficient Permissions
Symptoms:
Authentication succeeds, but data doesn’t sync
Errors referencing permissions or missing endpoints
Requirements:
The user generating the token should ideally be an Admin in Liongard or have sufficient API permissions.
Fix:
Have an admin generate the token
Retry connection
4️⃣ Copy/Paste Errors
Symptoms:
"Invalid Credentials" even though they look correct
Fix:
Ensure no trailing spaces
Avoid copying line breaks
Paste into a plaintext editor first to verify integrity
5️⃣ Connectivity / Network Issues
Symptoms:
Random failures
Region-specific issues
Timeouts
Fix:
Wait 2–5 minutes and retry
Verify no firewall is blocking outbound HTTPS to Gradient
Check Gradient status page if applicable
Summary 🤩
Issue | Likely Cause | Resolution |
Cannot authenticate | Wrong instance entered | Verify subdomain (us1, eu1, etc.) |
“Invalid credentials” | Token copied incorrectly / token expired | Regenerate token; verify no spaces |
Data not syncing after connect | Permissions issue | Ensure token created by admin-level user |
Random intermittent errors | Temporary service or network issue | Retry after a few minutes; validate connectivity |
“Secret not valid” | Secret not stored securely | Generate new token |
Security & Compliance Reminders 🧐
Never share your Access Key ID or Secret over email or chat.
Always store API tokens in a secure password manager.
Delete unused tokens from your Liongard account for best security.
Treat API tokens like passwords—because they are.
When to Contact Support 🦁
Contact Liongard Support if:
Authentication continues to fail after verifying Instance + Token
Permissions look correct but data still does not sync
Your Instance subdomain does not match expected patterns
You receive unfamiliar API or HTTP errors during setup
Contact Gradient Support if:
Authentication succeeds but no data appears inside Gradient
You see errors inside Synthesize UI during mapping or sync tasks
Reports or normalization workflows fail after connection
When contacting support, include:
Your Liongard Instance (us1/eu1/etc.)
Timestamp of failed attempts
Exact error message shown in Gradient
Confirmation that you generated a fresh token
Reference Documentation 📚
Third-Party Link Disclaimer ‼️
We may reference external third-party resources solely as additional guidance.
Liongard does not own, control, or guarantee the accuracy, security, or reliability of third-party sites. Please use them at your own discretion and risk.