Herald/Documentation
← All documentation
Owner setup

Owner Guide — Register Herald's LinkedIn App

Audience: Herald owner/developer (you), one time. ⚠️ IMPORTANT — LEAD TIME: Unlike Instagram, LinkedIn's Community Management API is NOT self-serve. LinkedIn manually vets your business + app before you can make a single posting call. This takes days to weeks. Start this now, in parallel — the app-creation and review clock is the long pole for LinkedIn testing. We can build the LinkedIn connector meanwhile, but a real LinkedIn connect can't happen until LinkedIn approves you.

⚠️VERIFY steps: LinkedIn's portal wording changes; do them live and report what you see.

What LinkedIn requires before approval

  • A registered legal business entity (sole proprietorship generally OK — it asks for a "registered legal organization").
  • A business-domain email (personal emails like gmail commonly fail vetting).
  • Org legal name, registered address, website, and a privacy policy URL.
  • A LinkedIn Company Page you administer, and a super admin of that Page to approve the app association.

If you don't have a business email / privacy-policy URL yet, that's the first thing to sort — it's the common rejection cause.

Steps

  1. Create Herald's own LinkedIn Company Page (if you don't have one) — this is Herald's page to legitimize the app, not the customer's page. https://www.linkedin.com/company/setup/new/

  2. Create the developer app

  3. Verify the app against the Page

    • App → Settings tab → Verify → Generate URL → send that URL to the Page's super admin (you) → approve (30-day window). The app then shows verified.

  4. Request the products

    • Products tab → request Community Management API → complete the Development Tier access form (business email, legal org name/address, website, privacy policy). LinkedIn reviews and vets. ← this is the wait.
    • Also request "Sign In with LinkedIn using OpenID Connect" (self-serve, instant) for openid/profile.

  5. Register the redirect URI

    • Auth tab → Authorized redirect URLs → add this exact URL: https://herald.leiritech.com/api/oauth/linkedin/callback (Herald's live deployment. On your own domain, use https://<your-domain>/api/oauth/linkedin/callback.)
    • Rules: HTTPS, absolute, exact match, no # fragment (query params are ignored in matching). Railway's cert satisfies these.

  6. Put the credentials into Herald (in the UI, encrypted) — the Auth tab shows Client ID and Client Secret. Open Herald → Settings → Platform apps → under LinkedIn, paste both → Save (stored encrypted, never in env).

Scopes Herald will request (once the product is approved)

openid profile w_organization_social rw_organization_admin r_organization_social (w_organization_social = post as the org; rw_organization_admin = discover which Pages you administer; r_organization_social = read metrics.)

What to hand me

  • LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET
  • The status of the Community Management API request (pending/approved) — real testing is gated on approval
  • Anything the portal said differently from the ⚠️VERIFY steps

Realistic sequencing

  • Do Instagram first (testable today). Submit the LinkedIn Community Management request today too so its review runs in the background. When LinkedIn approves, we do the real LinkedIn connect. Refresh tokens are only granted to "select partners" — if Herald isn't granted them, LinkedIn's 60-day tokens will require periodic reconnect (we'll design for that in Phase 6).