# Social Account Setup — SHIRE Marketing Forge Easy v1.3.0

The Accounts screen uses official OAuth. Ray signs in on the social network's own page; the Forge never asks for a Facebook, Instagram, LinkedIn, TikTok or Google password.

## Before starting

- Start the Forge at `http://127.0.0.1:4173`.
- Use a separate developer application for the SHIRE Marketing Forge.
- Do not reuse Kitchen Hero applications, credentials, social integrations or brand assets.
- Register callback addresses exactly, including `http`, `127.0.0.1`, port `4173` and the full path.
- Keep every App Secret/Client Secret private.

## Callback addresses

| Account | Callback to register |
|---|---|
| Facebook | `http://127.0.0.1:4173/api/oauth/callback/facebook` |
| Instagram | `http://127.0.0.1:4173/api/oauth/callback/instagram` |
| LinkedIn | `http://127.0.0.1:4173/api/oauth/callback/linkedin` |
| TikTok | `http://127.0.0.1:4173/api/oauth/callback/tiktok` |
| YouTube Shorts | `http://127.0.0.1:4173/api/oauth/callback/youtube_shorts` |

## Facebook and Instagram

Developer portal: `https://developers.facebook.com/apps/`

1. Create a Meta developer app owned for SHIRE Marketing Forge use.
2. Add Facebook Login and the products required for Page/Instagram professional-account access.
3. Add both Meta callback addresses above to the valid OAuth redirect URIs.
4. Keep the app in development while testing only with authorised app roles.
5. Request/review the Page and Instagram content permissions needed for the final publisher when the workflow is ready.
6. Record the **Meta App ID** and **Meta App Secret**.

The packaged OAuth bridge requests the configured Facebook Page scopes and Instagram professional-account publishing scopes. Meta may require app review and an eligible Page/professional Instagram account before those permissions are usable outside test roles.

## LinkedIn

Developer portal: `https://www.linkedin.com/developers/apps`

1. Create an application associated with the SHIRE3D LinkedIn Page where appropriate.
2. Add **Sign In with LinkedIn using OpenID Connect**.
3. Add **Share on LinkedIn** for member posting and request any organisation/Page products separately when needed.
4. Register the LinkedIn callback exactly.
5. Record the **Client ID** and **Client Secret**.

The default login scopes are `openid profile w_member_social`. Posting as an organisation can require additional products, permissions and a suitable Page administrator role.

## TikTok

Developer portal: `https://developers.tiktok.com/apps/`

1. Create a TikTok developer app.
2. Add **Login Kit for Desktop**.
3. Register the TikTok callback exactly. TikTok permits localhost/loopback desktop callbacks with a port.
4. Add the required user information and content scopes.
5. Apply separately for Content Posting API / Direct Post permissions when preparing live publishing.
6. Record the **Client Key** and **Client Secret**.

The Forge generates a fresh anti-forgery state token and a PKCE verifier/challenge for every TikTok login attempt.

## Google / YouTube Shorts

Developer console: `https://console.cloud.google.com/apis/credentials`

1. Create a Google Cloud project dedicated to SHIRE Marketing Forge.
2. Enable **YouTube Data API v3**.
3. Configure the OAuth consent screen.
4. Create an OAuth client that accepts the local callback above.
5. Add the YouTube callback exactly.
6. Record the **Client ID** and **Client Secret**.

The bridge requests OpenID profile access and the `youtube.upload` scope. A Short is uploaded through the standard YouTube video upload API; final publishing will also need a valid vertical video file and YouTube-compliant metadata.

## Save the developer credentials on Windows

1. Close the running Forge.
2. Double-click `configure-social-logins-windows.ps1`.
3. Enter only the developer App/Client values you created.
4. Leave platforms blank when they are not ready.
5. Restart with `start-windows.bat`.
6. Open **Accounts**.

The helper saves `social-oauth.secure.json`. App IDs remain plain identifiers; secrets are DPAPI-encrypted for the current Windows user. Do not send this file to anyone.

## Connect an account

When a card says **READY TO LOGIN**:

1. Press **Sign in with ...**.
2. Verify that the browser is on the genuine platform domain.
3. Sign in there and review the permissions shown.
4. Return to the Forge callback.
5. The card changes to **CONNECTED** for the current local server session.

Tokens are held in server memory only in v1.3.0. Closing the Forge clears them. This is intentionally conservative until persistent encrypted token storage and each live posting connector are reviewed separately.

## Publishing status

This version connects identities but does not make live social posting calls. Ray can still prepare, edit, freeze and test the queue safely. Live publishing should be added one platform at a time only after:

1. the relevant developer app is approved;
2. the exact page/channel/account is verified;
3. media requirements are implemented;
4. a read-only/dry-run validation passes;
5. Ray explicitly approves enabling that connector.
