OAuth and channel connect
Fix Invalid state, provider token errors, and network failures when you add a social channel in OpenQuok.
Connect your agent today
Draft from chat, review in your calendar, and publish only what you approve.
OAuth and channel connect
Add Channel sends you to the network and back. These errors mean something broke in that handoff.
See Connect a channel for the normal flow, status badges, and invite links.
Invalid state
You often see this as a flash message right after the provider redirects back to OpenQuok.
What it means: OpenQuok stores a one-time security token when you start connect. The network returns a matching state value. If the two do not match, or the stored token is gone, connect fails.
Common causes
- You started connect in one tab and finished in another.
- You refreshed the provider login page mid-flow.
- A privacy extension or strict browser settings blocked cookies between the redirect out and back.
- You waited longer than about an hour — OAuth state expires after that window.
- On self-host, the API could not read shared cache (see below).
What to try
- Open OpenQuok in one fresh tab. Do not bookmark the provider authorize page.
- Pause ad blockers or cookie shields for your OpenQuok domain during connect.
- Click Add Channel again from Home.
- If a half-added channel remains, remove it from Home, then connect again.
- Avoid private browsing if your browser clears cookies aggressively.
Provider rejected the code (invalid grant)
The network refused to swap the short-lived authorization code for an access token.
Common causes
- The same code was used twice — often from a double click or retry.
- The code expired (many providers allow only about a minute).
- The redirect URI in the developer console does not exactly match what OpenQuok sends (trailing slashes count).
What to try
- Start connect from scratch. Codes cannot be reused.
- Compare the redirect URI in the provider console with the URL OpenQuok documents for that integration.
Failed to fetch or network error on connect
The OpenQuok API could not reach the provider, or your browser could not reach the API.
| Symptom | What to try |
|---|---|
| Error on POST connect right after approve | Retry once. On Cloud, transient provider outages are common. |
| CORS or blocked preflight in the browser console | Fix frontend origin on the API — Production Vercel and Production deployment (CORS and canonical URLs), plus Vite configuration. |
| Self-host only | Check egress, DNS, and TLS from the server. Confirm Redis and env keys. |
Setup incomplete after OAuth
OAuth can succeed before you pick a Facebook Page, YouTube channel, Instagram professional account, or LinkedIn Page. The channel shows Setup incomplete until you click Complete setup on Home.