This guide answers the questions developers and agencies most often ask us when they connect a tool to QQCatalyst (QQ). It is based on partner and customer email threads (Feb-Oct 2026). Customer names and personal contacts are left out.
How to read it: each section is a set of short questions with direct answers, written the way a QQ API developer would answer you.
Authorization: Bearer <token>. This avoids CORS issues (section 2).orangepartnerprogram@vertafore.com.| Term | Meaning |
|---|---|
| QQ / QQC | QQCatalyst, the agency management system |
| QQID, VID | Your QQ account identifier and your Vertafore ID. We ask for both when we issue credentials |
| Callback URL (redirect URI) | Where QQ sends the browser after sign-in, carrying the authorization code |
| Authorization Code | The OAuth flow QQ supports: browser sign-in, then code, then token |
| Orange Partner Program | The Vertafore program that handles API access requests |
| Tenant | One agency's QQ account/database |
Key links
https://api.qqcatalyst.com/Helphttps://api.qqcatalyst.com/Home/Authenticationhttps://api.qqcatalyst.com/Home/HelpfulLinks. The sample OAuth client zip is tools.qqcatalyst.com/NewApiSample/QQOAuthSampleApiClient.zip.qqsolutions.com email addresses no longer exist, so mail to them bounces, and documentation for other Vertafore products doesn't apply to QQ.Q: How do I get API access?
A:
orangepartnerprogram@vertafore.com). Tell us your use case: internal automation or a third-party product, which tools you'll use, and whether you need read-only or read/write.Credentials belong to a QQ account, not to a location.
Q: Does a third-party developer need anything extra?
A: Yes. If a third party builds on a customer's behalf, they must contact us directly and sign an NDA. Agency Partnerships sends it. If you use an AI or LLM service to build the integration, we recommend an enterprise or secure license so personal information is protected.
Q: Is there a sandbox?
A: We setup sandbox login and API credentials on request through the Senior Product Owner. There is no self-service option and sandbox provisioning is subject to case-by-case review.
Credential hygiene
Use the Authorization Code grant. It is the only flow we document and support. client_credentials is not supported. The Password Credentials grant has worked for some people (for example in Postman, or until MFA was turned on), but it breaks with MFA/SSO accounts, has suddenly stopped working for others, and gives unhelpful errors (see section 3). Please don't build on it.
| Item | Value |
|---|---|
| Authorize URL | https://login.qqcatalyst.com/oauth/authorize?client_id={ID}&redirect_uri={URI}&response_type=code |
| Token URL | https://login.qqcatalyst.com/oauth/token |
| Token request |
POST, with header:Content-Type: application/x-www-form-urlencodedand body parameters: grant_type = authorization_codecode = the URL-decoded authorization codeclient_id = your Client IDclient_secret = your Client Secretredirect_uri = your registered callback URL
|
Client auth (client_id and client_secret) |
Send them either way. Both work: Option 1 - Authorization header (preferred, most used): Authorization: Basic <base64(client_id:client_secret)>. In this case leave client_id and client_secret out of the body.Option 2 - Request body: include client_id and client_secret as form parameters, as listed in the Token request row.Use one option, not both. The values are case-sensitive in either case. |
| Scope | Optional. If your tool insists on one, use openid (or the placeholder none) |
| Access token life | 7 days, then it refreshes. Each refresh returns a new refresh token, and the old one is not invalidated |
| Using the token | Send Authorization: Bearer <token>. You don't send the Client ID or Secret on API calls |
Two ways to get a token
Both ways use the same Authorization Code flow. Sign in with the native QQ login (QQ username and password) in the browser step. VSSO / SSO sign-in is not supported during token generation. That user's permissions apply to every API call you make.
code parameter.code and URL-decodes it before using it. The code in the redirect is URL-encoded (for example %2F instead of /, %3D instead of =), and sending it still encoded makes the token call fail with a 400 Bad Request.To see this working end to end, use the sample app (QQOAuthSampleApiClient.zip, linked on the Helpful Links page) as a reference.
Postman can run the sign-in for you, so you don't have to copy the code or URL-decode it by hand. Use this to test your credentials or to get a token manually.
| Field | Value |
|---|---|
| Grant Type | Authorization Code |
| Callback URL | your registered callback URL, exactly as registered with us |
| Auth URL | https://login.qqcatalyst.com/oauth/authorize |
| Access Token URL | https://login.qqcatalyst.com/oauth/token |
| Client ID | your Client ID |
| Client Secret | your Client Secret |
| Scope | openid (optional) |
| Client Authentication | Either option works: Send as Basic Auth header (preferred, most used) or Send client credentials in body |
Authorization: Bearer <token>) to make API calls.Q: What callback URL will I get?
A: By default we give you https://login.qqcatalyst.com/winformcallback/completed.htm. That works for desktop and Postman testing but not for web apps. Tell us your own callback URL and we'll register it.
Q: Can I register several callback URLs (dev, staging, prod)?
A: No. A Client ID/Secret pair supports exactly one callback. You have two options:
Q: My authorize request shows "An error has occurred". Why?
A: This usually means the callback in your authorize request doesn't match what is registered for your Client ID. Try these:
redirect_uri in your request exactly matches the callback registered for your Client ID, with no extra spaces, placeholder text or different casing.client_id is correct and in the right case, and that you sign in with a valid QQ user.orangepartnerprogram@vertafore.com with your Client ID (never the secret), the exact authorize URL you used, and the time of the attempt, and we'll check what is registered.Q: Is there a headless server-to-server flow?
A: No. The documented Authorization Code flow is the only way to get a token, and there is no separate token-generation endpoint. Sign in through the browser to get the token, then make the API calls from your server (see the next question).
Q: Can my web or mobile app call the QQ API directly from the browser (client-server model)?
A: No, don't do that. Integrate with the QQ API through your own server, not directly from the client, to avoid CORS issues.
login.qqcatalyst.com/oauth/token.Q: Should I use one org-wide connection, per-user connections, or a dedicated integration user?
A: We recommend per-user connections, each using the same client credentials. Every action is then attributed to the individual user, and their QQ roles and permissions are respected automatically.
Q: What about MFA?
A: MFA is supported with the Authorization Code flow. Notes:
scope or state parameters aren't interfering.Q: Can I sign in with VSSO / SSO when generating the token?
A: No. We don't support VSSO (SSO) authentication during token generation. The recommended option is the native QQ login. Use a QQ user that has a native username and password to authorize, and keep that password to letters and numbers only (see section 3).
| Symptom | Cause and fixes |
|---|---|
400 Bad Request on /oauth/token (HTML body) |
Try each of these: 1. Use grant_type=authorization_code (not password or client_credentials).2. URL-decode the authorization code before sending it. 3. Use the code immediately. It is single use and expires in about 60 seconds, so generate a fresh one if it was used or is old. 4. Send Content-Type: application/x-www-form-urlencoded.5. Make sure redirect_uri is exactly the registered callback.6. Check client_id and client_secret for typos and case.7. Compare against the sample app (Helpful Links) or a working Postman request |
401 Unauthorized on /oauth/token |
1. Re-check the Client ID and Secret exactly as issued (case-sensitive, no spaces). 2. Try the other client-auth method (Basic header instead of body, or the reverse). 3. Confirm with us that the credentials and callback belong together |
302 redirect to /Error.aspx?aspxerrorpath=/oauth/token (or 200 with an HTML login error) |
You are using the Password grant. Switch to Authorization Code (section 2) |
| "An unexpected error has occurred" / "An error has occurred" on authorize | See the authorize-error answer in section 2: match redirect_uri to the registered callback, confirm it is registered, check client_id, sign in with a valid QQ user, then contact us |
| 403 from a no-code tool but Postman works |
1. Do the manual code exchange in Postman and use the Bearer token in the tool (workaround). 2. Compare the tool's raw token request with the working Postman request. 3. Use openid as the scope if the tool requires one.4. There are no IP or non-browser restrictions on our token endpoint, so the tool's request is the place to look |
| Login works but nothing comes back after turning MFA on |
1. Log out and sign in again in a new session. 2. Re-authenticate the QQ connection to get a new token. 3. Test the same call in Postman with the old and new token. 4. Remove extra scope or state parameters from the authorize URL and retest
|
| Native login fails with special characters | Change the QQ password to letters and numbers only, and use the native QQ login (not SSO) |
GET v1/Customers/{id}/PersonalInformation returns 500 |
The customer is a Commercial customer. Use CustomerDetailSummary instead |
| 404 on email/attachment endpoints | Use entityType = Policy or Customer and a valid PolicyID or CustomerID |
Tips
Note: older walkthroughs and some tools suggest the Password grant. If it fails, switch to Authorization Code.
| Topic | Answer |
|---|---|
| Rate limit | 70 requests per second |
| Reducing calls | Use bulk-style endpoints: POST v1/PoliciesInfo/ByPolicyIds and GET v1/Policies/{id}/PolicyInfo |
| Pagination | Defined per endpoint, so check each endpoint's doc page. Parameters vary (page/rowCount vs pageNumber/pageSize) |
| User-agent | We don't block any today, but we may block specific user agents in future. Send a descriptive User-Agent and tell us what it is |
| Calling from a browser | Don't call the API directly from client-side code. Route requests through your server to avoid CORS issues and to keep credentials private (see section 2) |
| Webhooks | None. Poll instead (see section 5) |
| Read-only access | Enforced by QQ user permissions, not by the API credentials (see section 6) |
Contacts/LastModifiedCreated and Policies/LastModifiedCreated with a rolling window.FilesByPolicy).Q: Is there a "read-only" API credential?
A: No. API client credentials don't restrict what you can do. Authorization comes entirely from the user who signs in. For read-only behavior, create a dedicated QQ user with all create/edit permissions removed, and authorize with that user.
Questions? Reach out to orangepartnerprogram@vertafore.com for any questions.
Put these in your first message: exact URL, parameters, request and response bodies, timestamps with timezone, username, Client ID, and what you expected vs. what you got. A complete first message gets you an answer faster.