Cache and reuse Instagram sessions in JxInsta

Save your JxInsta bearer token or session cookies to disk after first login and restore them with getInstance() to skip re-authentication on future runs.

Every time you call the JxInsta constructor with a username and password, JxInsta performs a full login request to Instagram. Doing this repeatedly from the same account increases the risk of triggering a checkpoint, rate limit, or temporary block. Session caching lets you save the credentials returned after a successful login — a bearer token for the Mobile module, or a session cookie and CSRF token for the Web module — and restore them on later runs without logging in again.

Why caching matters

Instagram is sensitive to repeated login attempts. Caching your session reduces the number of login requests your account makes and lowers the likelihood of triggering a CHECKPOINT_REQUIRED or RATE_LIMITED error.

Each module exposes a static getInstance factory method that accepts previously saved credentials and returns a ready-to-use JxInsta instance. The session is considered valid until Instagram expires it, which typically happens after a period of inactivity or when you log out from another device.

Save and restore a session

Mobile

The Mobile module uses a single bearer token. Save insta.token to a file after login, then pass it to JxInsta.getInstance(token) on subsequent runs.

Saving the token

Save token to disk

import com.jxinsta.mobile.JxInsta;
import java.nio.file.Files;
import java.nio.file.Path;

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

// Persist the token for later runs
Path tokenFile = Path.of("session.token");
Files.writeString(tokenFile, insta.token);
System.out.println("Token saved.");

Loading the token

Load token from disk

import com.jxinsta.mobile.JxInsta;
import java.nio.file.Files;
import java.nio.file.Path;

Path tokenFile = Path.of("session.token");
String token = Files.readString(tokenFile).strip();

// Reuse the existing token — no login request sent
JxInsta insta = JxInsta.getInstance(token);
System.out.println("Session restored.");

Putting it together

Mobile session caching with fallback

import com.jxinsta.mobile.JxInsta;
import com.jxinsta.mobile.InstagramException;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

Path tokenFile = Path.of("session.token");
JxInsta insta;

if (Files.exists(tokenFile)) {
    String token = Files.readString(tokenFile).strip();
    insta = JxInsta.getInstance(token);
    System.out.println("Reused cached token.");
} else {
    insta = new JxInsta("your_username", "your_password");
    Files.writeString(tokenFile, insta.token);
    System.out.println("Logged in and saved token.");
}

Web

The Web module uses two values: a session cookie (insta.session) and a CSRF token (insta.crsf). Save both to disk after login and pass them to JxInsta.getInstance(session, crsf) on subsequent runs.

Saving the session

Save session and CSRF to disk

import com.jxinsta.web.JxInsta;
import java.nio.file.Files;
import java.nio.file.Path;

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

// Persist both values — one per line
Path sessionFile = Path.of("session.txt");
Files.writeString(sessionFile, insta.session + "\n" + insta.crsf);
System.out.println("Session saved.");

Loading the session

Load session and CSRF from disk

import com.jxinsta.web.JxInsta;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

Path sessionFile = Path.of("session.txt");
List<String> lines = Files.readAllLines(sessionFile);
String session = lines.get(0).strip();
String crsf = lines.get(1).strip();

// Reuse the existing session — no login request sent
JxInsta insta = JxInsta.getInstance(session, crsf);
System.out.println("Session restored.");

Putting it together

Web session caching with fallback

import com.jxinsta.web.JxInsta;
import com.jxinsta.web.InstagramException;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

Path sessionFile = Path.of("session.txt");
JxInsta insta;

if (Files.exists(sessionFile)) {
    List<String> lines = Files.readAllLines(sessionFile);
    String session = lines.get(0).strip();
    String crsf = lines.get(1).strip();
    insta = JxInsta.getInstance(session, crsf);
    System.out.println("Reused cached session.");
} else {
    insta = new JxInsta("your_username", "your_password");
    Files.writeString(sessionFile, insta.session + "\n" + insta.crsf);
    System.out.println("Logged in and saved session.");
}

Token expiry and re-authentication

Cached sessions do not last forever. Instagram can expire a token or session at any time — typically after extended inactivity, a password change, or a security event on the account.

When a cached session has expired, subsequent API calls will throw InstagramException with reason LOGIN_EXPIRED. Handle this by deleting the cached file and performing a fresh login.

Handle expired session

import com.jxinsta.mobile.InstagramException;
import java.nio.file.Files;
import java.nio.file.Path;

Path sessionFile = Path.of("session.token"); // adjust path per module

try {
    // ... use insta for API calls
} catch (InstagramException e) {
    if (e.getReason() == InstagramException.Reasons.LOGIN_EXPIRED) {
        Files.deleteIfExists(sessionFile);
        System.out.println("Session expired. Delete cache and re-authenticate.");
    } else {
        throw e;
    }
}

Catch LOGIN_EXPIRED at the top of your run loop so you can automatically delete the stale cache file and retry the full login flow without manual intervention.

Do not share session files between different accounts or machines. Reusing a token or session on an unexpected IP address can trigger an CHECKPOINT_REQUIRED checkpoint. See the challenges guide for details.