Instagram Provider

Configure Instagram OAuth for authentication in your Next.js application using NextAuth.js.

Documentation

https://developers.facebook.com/docs/instagram-basic-display-api/getting-started

Configuration

https://developers.facebook.com/apps/

Instagram Basic Display API Setup

Follow these steps to configure Instagram OAuth:

Step 1: Create a Facebook App

1. Go to Facebook Developers
2. Click Create App
3. Select Consumer or None (Build something else)
4. Enter your app display name and contact email
5. Click Create App

Step 2: Add Instagram Basic Display Product

1. In your app dashboard, scroll down to find Instagram Basic Display
2. Click Set Up
3. Scroll down and click Create New App
4. Enter a display name for your Instagram app

Step 3: Configure Basic Display Settings

1. Navigate to Instagram Basic Display → Basic Display in the left sidebar
2. Fill in the required URLs:

Step 4: Setup for Local Development

Since Instagram requires HTTPS, use ngrok for local development:

# Install ngrok
npm install -g ngrok

# Start your Next.js app
npm run dev

# In another terminal, create an HTTPS tunnel
ngrok http 3000

Use the HTTPS URL provided by ngrok (e.g., https://abc123.ngrok.io) as your redirect URI:

https://abc123.ngrok.io/api/auth/callback/instagram

Step 5: Add Test Users

1. Go to Roles → Instagram Testers
2. Click Add Instagram Testers
3. Enter the Instagram username of your test account
4. The test user must accept the invitation in their Instagram app:
   Settings → Apps and Websites → Tester Invites → Accept

Step 6: Get App ID and Secret

1. Go to Instagram Basic Display → Basic Display
2. Copy the Instagram App ID and Instagram App Secret
3. Add them to your .env.local file:

# .env.local
INSTAGRAM_CLIENT_ID=your-instagram-app-id
INSTAGRAM_CLIENT_SECRET=your-instagram-app-secret

Options

The Instagram Provider comes with a set of default options. You can override any of the options to suit your own use case.

Instagram Provider options →

Example

// src/core/lib/auth.ts
import InstagramProvider from "next-auth/providers/instagram";

export const authOptions: NextAuthOptions = {
  providers: [
    InstagramProvider({
      clientId: process.env.INSTAGRAM_CLIENT_ID!,
      clientSecret: process.env.INSTAGRAM_CLIENT_SECRET!,
    }),
  ],
};

Usage in Component

// src/features/auth/components/social-login-buttons.tsx
"use client";

import { signIn } from "next-auth/react";
import { Button } from "@/components/ui/button";

export function InstagramLoginButton() {
  return (
    <Button
      variant="outline"
      onClick={() => signIn("instagram")}
    >
      Sign in with Instagram
    </Button>
  );
}

Handling No Email

Since Instagram doesn't return email, you need to handle user identification differently:

// src/core/lib/auth.ts
export const authOptions: NextAuthOptions = {
  providers: [
    InstagramProvider({
      clientId: process.env.INSTAGRAM_CLIENT_ID!,
      clientSecret: process.env.INSTAGRAM_CLIENT_SECRET!,
    }),
  ],
  callbacks: {
    async signIn({ account, profile }) {
      if (account?.provider === "instagram") {
        // Instagram doesn't provide email
        // Use the Instagram user ID as unique identifier
        return true;
      }
      return true;
    },
    async jwt({ token, account, profile }) {
      if (account?.provider === "instagram") {
        // Store Instagram-specific data
        token.instagramId = account.providerAccountId;
        token.username = (profile as { username?: string })?.username;
      }
      return token;
    },
  },
};

Troubleshooting

Common Errors

App Review for Production

To allow any Instagram user to log in (not just testers), you need to submit your app for review:

1. Go to App Review → Permissions and Features
2. Request the instagram_graph_user_profile permission
3. Prepare screenshots and a detailed description of your app
4. Submit for review

Related

• Facebook Provider
• Google Provider
• LINE Provider
• Authentication Design Pattern