{"id":16713,"library":"better-auth-instagram","title":"Better Auth Instagram Provider","description":"The `better-auth-instagram` package provides an Instagram OAuth provider specifically designed to integrate with the `better-auth` authentication framework. Currently at version 0.0.7, it functions as a plugin, allowing developers to easily add 'Login with Instagram' functionality to their TypeScript applications. It leverages `@better-fetch/fetch` for making robust API requests and `zod` for schema validation, aligning with the `better-auth` ecosystem's focus on type-safety and developer experience. While `better-auth` (currently at 1.4.0) offers a comprehensive, framework-agnostic authentication solution with a plugin-based architecture, `better-auth-instagram` simplifies the complexities of Instagram's OAuth flow, requiring proper setup of an Instagram Business Login API application. Its release cadence is tied to the `better-auth` ecosystem, focusing on incremental improvements and compatibility. Key differentiators include its tight integration with `better-auth`'s plugin system and built-in type safety with Zod.","status":"active","version":"0.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/manolo-in/better-auth-instagram","tags":["javascript","instagram","meta","better-auth","oauth","typescript"],"install":[{"cmd":"npm install better-auth-instagram","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-instagram","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-instagram","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for making robust HTTP requests to the Instagram API, supporting schema validation and advanced fetch capabilities.","package":"@better-fetch/fetch","optional":false},{"reason":"This package is an OAuth provider plugin for the core better-auth framework, essential for its functionality.","package":"better-auth","optional":false},{"reason":"Used for runtime schema validation of API responses and data structures, ensuring type safety and data integrity within the better-auth ecosystem.","package":"zod","optional":false}],"imports":[{"note":"Primarily used with ESM. The `instagram` function is a helper to configure the Instagram provider directly within `betterAuth`'s plugins array.","wrong":"const { instagram } = require('better-auth-instagram');","symbol":"instagram","correct":"import { instagram } from 'better-auth-instagram';"},{"note":"Used for advanced configuration of the Instagram provider, especially when integrating via `better-auth`'s `genericOAuth` plugin to specify custom scopes, fields, or email handling.","wrong":"import instagramConfig from 'better-auth-instagram/config';","symbol":"instagramConfig","correct":"import { instagramConfig } from 'better-auth-instagram';"},{"note":"While not directly from `better-auth-instagram`, this is the core import for the `better-auth` framework into which `better-auth-instagram` plugs. Always a named import.","wrong":"import betterAuth from 'better-auth';","symbol":"betterAuth","correct":"import { betterAuth } from 'better-auth';"}],"quickstart":{"code":"import { betterAuth } from 'better-auth';\nimport { instagram } from 'better-auth-instagram';\nimport { createAuthClient } from 'better-auth/client';\nimport { genericOAuthClient } from 'better-auth/client/plugins';\n\n// Server-side Better Auth instance configuration\nexport const auth = betterAuth({\n  plugins: [\n    instagram(), // Adds the Instagram OAuth provider\n  ],\n  // ... other better-auth configurations like database, secret, etc.\n});\n\n// Client-side Better Auth client instance configuration\n// This should typically be in a separate client-side file\nexport const authClient = createAuthClient({\n  plugins: [\n    genericOAuthClient() // Required for OAuth client-side flows\n  ]\n});\n\n// Example of initiating the sign-in flow on the client-side\nasync function signInWithInstagram() {\n  if (typeof window !== 'undefined') {\n    console.log('Initiating Instagram sign-in...');\n    await authClient.signIn.oauth2({\n      providerId: 'instagram',\n      callbackURL: '/dashboard', // URL to redirect to after successful auth\n      errorCallbackURL: '/login?error=instagram_failed'\n    });\n  }\n}\n\n// Call this function from a UI element, e.g., a button click\nsignInWithInstagram();\n\n// In your .env file:\n// INSTAGRAM_APP_ID=\"your_instagram_app_id\"\n// INSTAGRAM_APP_SECRET=\"your_instagram_app_secret\"\n// BETTER_AUTH_SECRET=\"super_secret_key_at_least_32_chars\"\n// BETTER_AUTH_URL=\"http://localhost:3000\" // Base URL of your app for callbacks","lang":"typescript","description":"This quickstart demonstrates the basic server-side setup of `better-auth` with the `better-auth-instagram` plugin and how to initiate the client-side OAuth flow."},"warnings":[{"fix":"Review and update your Instagram Developer App settings to ensure it's configured for 'Instagram Business Login' and not 'Basic Display'. Verify required permissions/scopes are enabled and the authorized redirect URI matches your application's callback URL (e.g., `http://localhost:3000/api/auth/oauth2/callback/instagram`).","message":"The Instagram Basic Display API reached End-of-Life on December 4, 2024. While `better-auth-instagram` is designed to work with the Instagram Business Login API, users *must* ensure their Instagram app is correctly configured for the Business Login API and not the deprecated Basic Display API. Failure to do so will result in authentication failures.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"Carefully review release notes for any updates. Pin exact versions in your `package.json` to prevent unexpected behavior with `better-auth-instagram` and its peer dependencies. Consider contributing to help stabilize the API.","message":"As a pre-release version (0.0.7), the package's API surface or internal behavior might change without adhering to strict semantic versioning, potentially leading to breaking changes between minor or patch versions.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Follow the Instagram Developer documentation for setting up an Instagram app for 'Instagram Business Login'. Ensure the app is in 'Live Mode' or that all users attempting to log in are added as 'Testers' and have accepted the invitation.","message":"Instagram applications must be properly configured, including adding the 'Instagram product', setting up 'Instagram business login', and accepting 'Tester Invites' if the app is not live. Failing to do so will prevent login for non-tester accounts.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Implement database hooks or custom logic within your `betterAuth` configuration to fetch and update user profile data from the Instagram API after a successful authentication event. The package provides utility functions for Instagram API interaction for this purpose.","message":"By default, `better-auth` and its plugins like `better-auth-instagram` do not automatically update user profile data (e.g., username, profile picture) upon account linking or subsequent logins. This requires manual implementation using database hooks.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure that `INSTAGRAM_APP_ID` and `INSTAGRAM_APP_SECRET` are correctly configured in your server's environment variables (e.g., `.env` file) and are accessible to your `better-auth` instance. Confirm they match the credentials from your Instagram Developer App.","message":"Environment variables for `INSTAGRAM_APP_ID` and `INSTAGRAM_APP_SECRET` must be set correctly. Incorrect or missing values will lead to failed OAuth flows.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure that the callback handler processes the authorization code promptly and only once. Check server logs for any repeated attempts or slow responses during the code exchange phase. Verify server time synchronization.","cause":"The authorization code exchanged during the OAuth flow is single-use and short-lived. This error often indicates a race condition, a double-submission, or a delay in processing.","error":"Error: invalid_grant - The authorization code has expired or been revoked."},{"fix":"Go to your Instagram Developer App settings. Under 'Instagram Basic Display' or 'Instagram Business Login' (depending on your setup), navigate to 'Client OAuth Settings' and ensure the `http://localhost:3000/api/auth/oauth2/callback/instagram` (or your production URL) is added and exactly matches the URI used in your `better-auth` configuration.","cause":"The `redirect_uri` parameter sent in the OAuth authorization request does not exactly match one of the 'Valid OAuth Redirect URIs' configured in your Instagram Developer App.","error":"redirect_uri_mismatch: The redirect URI in the request does not match the ones authorized for the client application."},{"fix":"This is expected user behavior. Handle this gracefully in your client-side application, perhaps by redirecting them back to a login page or displaying a message indicating that Instagram login was canceled.","cause":"The user explicitly declined the authentication request or revoked permissions during the Instagram OAuth process.","error":"Error: User canceled authentication or denied permissions."},{"fix":"Inspect the detailed error message for the specific field that failed validation. This might indicate an unexpected API response format from Instagram or a mismatch in your `instagramConfig` or data processing logic. If it's an upstream API change, an update to `better-auth-instagram` might be needed.","cause":"Input data (e.g., API response, profile data) failed schema validation defined by Zod within the package or your custom configurations.","error":"ZodError: Invalid input"}],"ecosystem":"npm"}