Login with credentials

Log in to Instagram with a username and password using JxInsta’s Mobile or Web module. Covers token retrieval, error handling, and 2FA.

JxInsta supports two authentication modules: Mobile and Web. The Mobile module authenticates via Instagram’s private mobile API and returns a bearer token. The Web module authenticates via the browser-based API and returns a session cookie and CSRF token. Choose the module that best fits your use case — both expose a constructor that accepts a username and password.

How authentication works

Mobile

The Mobile module (com.jxinsta.mobile.JxInsta) sends credentials to Instagram’s mobile API endpoint. On success, Instagram returns a bearer token that you use to authorize subsequent requests. After login, this token is stored in the token field on your JxInsta instance.

Mobile login

import com.jxinsta.mobile.JxInsta;

JxInsta insta = new JxInsta("your_username", "your_password");

// Bearer token is now available
String token = insta.token;
System.out.println("Authenticated. Token: " + token);

Store insta.token after a successful login. You can pass it to JxInsta.getInstance(token) on future runs to skip re-authentication.

Web

The Web module (com.jxinsta.web.JxInsta) authenticates via Instagram’s web interface. On success, Instagram sets a session cookie and a CSRF token. After login, these are stored in the session and crsf fields on your JxInsta instance.

Web login

import com.jxinsta.web.JxInsta;

JxInsta insta = new JxInsta("your_username", "your_password");

// Session cookie and CSRF token are now available
String session = insta.session;
String crsf = insta.crsf;
System.out.println("Authenticated. Session: " + session);

Store both insta.session and insta.crsf after login. Pass them to JxInsta.getInstance(session, crsf) on future runs to reuse the session without re-authenticating.

Handle authentication errors

Both modules throw InstagramException when login fails. Call getReason() on the exception to inspect the failure cause and respond appropriately.

Mobile

Mobile error handling

import com.jxinsta.mobile.JxInsta;
import com.jxinsta.mobile.InstagramException;

try {
    JxInsta insta = new JxInsta("your_username", "your_password");
    String token = insta.token;
} catch (InstagramException e) {
    switch (e.getReason()) {
        case INCORRECT_PASSWORD:
            System.err.println("Wrong password. Check your credentials.");
            break;
        case TWO_FACTOR_REQUIRED:
            System.err.println("2FA is enabled. Handle the two-factor flow.");
            break;
        case CHECKPOINT_REQUIRED:
            System.err.println("Checkpoint triggered. See the challenges guide.");
            break;
        case RATE_LIMITED:
            System.err.println("Too many requests. Wait before retrying.");
            break;
        case LOGIN_EXPIRED:
            System.err.println("Session expired. Log in again.");
            break;
        case SENTRY_BLOCK:
            System.err.println("Account blocked by Instagram's sentry.");
            break;
        default:
            System.err.println("Login failed: " + e.getMessage());
    }
} catch (IOException e) {
    System.err.println("Network error: " + e.getMessage());
}

Web

Web error handling

import com.jxinsta.web.JxInsta;
import com.jxinsta.web.InstagramException;

try {
    JxInsta insta = new JxInsta("your_username", "your_password");
    String session = insta.session;
    String crsf = insta.crsf;
} catch (InstagramException e) {
    switch (e.getReason()) {
        case INCORRECT_PASSWORD:
            System.err.println("Wrong password. Check your credentials.");
            break;
        case TWO_FACTOR_REQUIRED:
            System.err.println("2FA is enabled. Handle the two-factor flow.");
            break;
        case CHECKPOINT_REQUIRED:
            System.err.println("Checkpoint triggered. See the challenges guide.");
            break;
        case RATE_LIMITED:
            System.err.println("Too many requests. Wait before retrying.");
            break;
        case FORBIDDEN:
            System.err.println("Action forbidden by Instagram.");
            break;
        case UNKNOWN_LOGIN_ERROR:
            System.err.println("Unrecognised login error.");
            break;
        default:
            System.err.println("Login failed: " + e.getMessage());
    }
} catch (IOException e) {
    System.err.println("Network error: " + e.getMessage());
}

Two-factor authentication

When an account has 2FA enabled, the constructor throws InstagramException with reason TWO_FACTOR_REQUIRED. JxInsta does not complete the 2FA challenge automatically — you need to intercept this case and supply the one-time code through the appropriate follow-up method for your module.

Attempting to re-invoke the constructor with the same credentials after a TWO_FACTOR_REQUIRED error will trigger another challenge request and may cause Instagram to rate-limit or checkpoint the account.

Checkpoint handling

If Instagram detects unusual activity during login, it throws InstagramException with reason CHECKPOINT_REQUIRED. This can happen due to too many login attempts, a new IP address, or signs of automated behaviour. See the challenges guide for a full breakdown of each checkpoint type and how to resolve it.