# Instagram Integration API (Spring Boot) ## Overview This project implements the core integration with Instagram via the official Meta Graph API. The goal is to provide a stable foundation layer for all future product features by exposing **three reusable REST endpoints** that handle: 1. **User account linking (OAuth)** 2. **Data fetching (profile, media, followers)** 3. **Token refresh and account unlinking** --- ## Features / APIs ### Link Instagram Account **Purpose:** Allow a user to link their Instagram account using Meta OAuth and persist the user-scoped access token. **Endpoints** ``` GET /api/v1/instagram/link GET /api/v1/instagram/callback ``` **Responsibility** - Initiate Meta OAuth login - Callback handles authorization code and exchanges for access token - Store token info with metadata: - userId (internal app ID) - instagramUserId - scopes - expiry - accountType (Personal / Business / Creator) --- ### Instagram Data Fetch **Purpose:** Fetch Instagram user data via stored token and persist in the database. **Endpoint** ``` POST /api/v1/instagram/fetch ``` **Data retrieved & stored** - Profile details - Recent media - Followers list (conditionally based on account type and scopes) - Pagination handled --- ### Refresh / Unlink Instagram **Purpose:** Manage token refresh or revoke access. **Endpoints** ``` POST /api/v1/instagram/refresh DELETE /api/v1/instagram/unlink ``` **Responsibility** - Detect expired tokens - Try long-lived refresh (where applicable) - If expired or revoked, require re-auth - Revoke access at Meta and clear local data --- ## Technical Stack - Java - Spring Boot - Spring Security (OAuth utilities) - Spring Data JPA - Relational SQL Database (Postgres / MySQL / H2 for local) - Swagger / OpenAPI - Optional: RestFB or direct Graph API HTTP calls --- ## Environment Variables / Config Add the following to your environment (or `application.yml`): ``` META_APP_ID=<your-meta-app-id> META_APP_SECRET=<your-meta-app-secret> META_REDIRECT_URI=<your-redirect-uri> DATABASE_URL=<your-database-url> DATABASE_USERNAME=<your-db-user> DATABASE_PASSWORD=<your-db-password> ``` --- ## Meta App Setup Instructions ### 1. Create Meta Developer Account 1. Visit https://developers.facebook.com 2. Log in with a Facebook account 3. Accept developer terms --- ### 2. Create a New App 1. Click **My Apps → Create App** 2. Choose **Business** app type 3. Enter: - App Name (e.g., Instagram Integration API) - Contact Email 4. Click **Create App** --- ### 3. Configure Login & Permissions #### Add Facebook Login 1. On the app dashboard, go to **Use cases** 2. Find **Authenticate and request data from users with Facebook Login** 3. Click **Set Up** #### Add Instagram Graph API 1. Go to **Use cases** 2. Find **Instagram Graph API** 3. Click **Set Up** --- ### 4. Set OAuth Redirect URI 1. Go to **Facebook Login → Settings** 2. Under **Valid OAuth Redirect URIs**, add: ``` <META_REDIRECT_URI> ``` Example: ``` https://<ngrok-id>.ngrok.io/api/v1/instagram/callback ``` Must match exactly --- ### 5. App Credentials Under **Settings → Basic**, note: ``` APP_ID APP_SECRET ``` Use these in environment variables. --- ### 6. Add Instagram Test Users 1. Go to **App Roles → Roles** 2. In **Instagram Testers**, add your IG username 3. On Instagram, accept the invite: - **Settings → Accounts Center → Apps and Websites** - Accept tester invite --- ## OAuth Scopes to Request These are required in the OAuth link: ``` instagram_basic pages_show_list instagram_manage_insights ``` --- ## Testing Use Swagger UI: ``` [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html) ``` Ensure endpoints: - Link + callback work - Fetch works - Refresh/unlink work --- ## Acceptance Criteria 1. Project runs locally: ``` mvn spring-boot:run ``` 2. OAuth works end-to-end 3. Tokens stored securely per user 4. Account type persisted 5. Conditional fetch based on account type 6. Clear refresh logic 7. Unlink revokes access and cleans data 8. Swagger documented APIs 9. Postman/cURL scripts for: - Link start - OAuth callback - Fetch - Refresh - Unlink --- we allready have code jsut help me create Meta app and cofigure and run that code