Meta Threads

Configure Meta Threads OAuth for Openquok — Meta app, redirect URIs, THREADS_APP_ID and THREADS_APP_SECRET, and testers.

3 min read

Overview

Threads publishing uses Meta’s Threads API behind an OAuth 2.0 flow. You need a Meta for Developers app with Threads access, valid OAuth redirect URIs, and backend env vars THREADS_APP_ID and THREADS_APP_SECRET.

For Meta’s product requirements and API surface, see Threads API documentation. The steps below add Openquok-specific URLs and env wiring.

Complex setup

Meta’s onboarding can take time (business verification, app review, tester invites). If something fails, double-check redirect URIs **character-for-character** and that the backend picked up new env vars after a restart.

Backend environment

Openquok reads Threads credentials only through backend/config/GlobalConfig.ts (populated via getEnv from backend/config/envHelper.ts). Set:

THREADS_APP_ID — **Threads App ID** from the Meta app dashboard
THREADS_APP_SECRET — **Threads App Secret** (treat as confidential)

Copy from backend/.env.development.example into backend/.env.development.local, fill values, then restart the backend process.

The frontend base URL used for OAuth redirects comes from FRONTEND_DOMAIN_URL (default http://localhost:5173 for local Vite).

OAuth redirect URI (what to enter in Meta)

Meta redirects the browser back to your web app after consent—not to /api/v1. The backend builds the redirect from FRONTEND_DOMAIN_URL plus the path /integrations/social/threads.

Production (when FRONTEND_DOMAIN_URL is https://…): register
https://YOUR-FRONTEND-DOMAIN/integrations/social/threads
Local HTTP (default dev): the backend wraps non-HTTPS origins with a public HTTPS relay so the authorize URL stays valid for Meta. Register exactly what your running backend would send, for example:
https://redirectmeto.com/http://localhost:5173/integrations/social/threads
if FRONTEND_DOMAIN_URL is http://localhost:5173.

If you change port or host, the redirect string changes—always match Meta’s field to the URI your backend encodes (you can copy it from the generated authorize URL’s redirect_uri query parameter).

Other tools may use different local ports

Some stacks document localhost:4200 or Docker on :5000 for local redirects. Openquok’s default web dev server is typically 5173 (Vite)—use your actual FRONTEND_DOMAIN_URL, not another project’s port, unless you deliberately run the web app elsewhere.

Meta dashboard form

On the Meta app **Threads API** settings screen, you often must **click** each OAuth / callback URL field so it is “active” before the form will save. Uninstall / delete callback URLs may still require placeholder values even if unused.

Meta app setup (summary)

Create and scope a Meta app

Create an app in Meta for Developers, request Access the Threads API, add products/scopes such as threads_basic and threads_content_publish, and complete the dashboard wizard until customization is finished. Follow Threads API get started for current requirements.

Paste App ID and App Secret into the backend

In the Meta app Threads / Settings area, copy Threads App ID → THREADS_APP_ID, and App Secret → THREADS_APP_SECRET. Restart the backend.

Register OAuth redirect URIs

Add the production and/or local redirect URIs from the section above. They must match what Openquok sends in the authorize request.

Add testers and accept Threads invites

Add Threads Testers under app roles, then on Threads open Website permissions invites and accept the app for the test account you use.

How Openquok uses the flow

Authorize URL is produced by the backend (session or programmatic API); the user signs in with Meta and returns to the frontend route with an authorization code.
The web client then calls the backend social-connect endpoint with code, state, and timezone so the server can exchange the code and persist the channel.

API prefix defaults to /api/v1 (see API_PREFIX). Typical patterns include session routes under /integrations and org–key routes under /public—see route modules in backend/routes for the exact paths in your checkout.