How does it work ?

To link an Instagram account with Unipile, you can offer users two authentication methods:

Using credentials (username & password) - A dedicated Instagram session is created for Unipile. If Instagram invalidates the session or requires authentication again, the account status changes to disconnected (🟡 Authentication required).
Using cookies (sessionid) - The session is shared from an existing browser session where the cookie was collected. If the user logs out from that browser or the cookie expires, the account will become disconnected (🟡 Authentication required).

Link with Hosted Authentication

To link Instagram accounts using Hosted Authentication, follow the Authenticate with Hosted Auth guide.

At the Create Auth Link step:

Set INSTAGRAM as the providers.
By default, Hosted Authentication only displays the credentials method. To also allow the cookies method, include it in the allow_methods field of the Instagram configuration.

Server code

// ...

const response = await unipile
  .hostedAuth
  .createAuthLink({
    providers: "INSTAGRAM",
    expires_on: dayjs().add(10, 'minutes').toISOString()
    redirect_uri: "https://myapp.com/link-account/callback",
    config: {
      instagram: {
        allow_methods: ["credentials", "cookies"],
      }
    }
  });

// ...

# ...

response = hosted_auth_api.create_auth_link(
    {
        "providers": "INSTAGRAM",
        "expires_on": "2025-05-05T00:00:00.000Z",
        "redirect_uri": "https://myapp.com/link-account/callback",
        "config": {
            "instagram": {
                "allow_methods": ["credentials", "cookies"],
            }
        },
    }
)

# ...

curl --request POST \
     --url https://api.unipile.com/v2/auth/link \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "providers": "INSTAGRAM",
  "redirect_uri": "https://myapp.com/link-account/callback",
  "expires_on": "2025-05-05T00:00:00.000Z",
  "config": {
    "instagram": {
      "allow_methods": ["credentials", "cookies"]
    }
  }
}
'

Link with Custom Authentication

To build a custom authentication wizard for Instagram accounts, follow the Credentials Flow guide.

Client code

const data = await startAuthIntent({
  provider: "instagram",
  credentials: {
    username,
    password,
  },
});

To let users authenticate with cookies, create a form that takes the sessionid cookie. Then, forward that value instead of the username and password.

Client code

const data = await startAuthIntent({
  provider: "instagram",
  credentials: {
    sessionid,
  },
});