What Are the Different Session Token Types Nitter Uses for Authentication?

Nitter supports two distinct session token types—OAuth 1.0a tokens and web session cookies—represented by the SessionKind enum in the source code.

Nitter requires authentication to fetch data from Twitter's API, and the project implements a flexible session system to handle different authentication methods. Understanding the different session token types Nitter uses for authentication is essential for developers deploying private instances or contributing to the codebase. These token types are defined in the core type system and parsed from raw JSON configurations to enable API communication.

Overview of Nitter Session Token Types

The authentication architecture centers on the SessionKind enum defined in src/types.nim【/cache/repos/github.com/zedeus/nitter/master/src/types.nim†L30-L33】. This enum distinguishes between two authentication strategies:

• OAuth 1.0a tokens (SessionKind.oauth) - The classic API authentication flow using consumer keys and secrets
• Web session cookies (SessionKind.cookie) - Browser-based authentication using Twitter's web session cookies

Both types store different underlying credentials but conform to the same Session object structure, allowing the codebase to handle authentication polymorphically.

OAuth 1.0a Tokens (SessionKind.oauth)

The OAuth token type implements the traditional Twitter API authentication flow. When using this method, the session stores the consumer's OAuth token and OAuth secret as raw credentials.

According to src/experimental/types/session.nim, the raw JSON representation for OAuth sessions includes the fields oauthToken and oauthTokenSecret【/cache/repos/github.com/zedeus/nitter/master/src/experimental/types/session.nim†L3-L9】. The parser in src/experimental/parser/session.nim handles this variant by extracting these values and deriving the user ID from the token prefix when the kind field is empty or explicitly set to "oauth"【/cache/repos/github.com/zedeus/nitter/master/src/experimental/parser/session.nim†L6-L30】.

# OAuth session example

let oauthSession = Session(
  kind: SessionKind.oauth,
  id: 1234567890,                     # numeric user id

  username: "alice",
  oauthToken: "12345-abcdefg...",     # OAuth token

  oauthSecret: "hijklmnop..."         # OAuth secret

)

Web Session Cookies (SessionKind.cookie)

The cookie-based authentication relies on Twitter's web session infrastructure rather than API keys. This method uses two specific cookie values extracted from an authenticated browser session.

As implemented in src/experimental/types/session.nim, cookie sessions store the auth token (auth_token) and the CSRF token (ct0)【/cache/repos/github.com/zedeus/nitter/master/src/experimental/types/session.nim†L3-L9】. The parser recognizes this type when the kind field equals "cookie", extracting authToken and ct0 from the JSON payload (or using a provided id if present)【/cache/repos/github.com/zedeus/nitter/master/src/experimental/parser/session.nim†L6-L30】.

The repository includes a utility script at tools/create_session_browser.py that automates browser login to generate these cookie values, illustrating the practical extraction of web session tokens for Nitter configuration.

# Cookie session example

let cookieSession = Session(
  kind: SessionKind.cookie,
  id: 987654321,
  username: "bob",
  authToken: "auth_token_here",       # value of the auth_token cookie

  ct0: "ct0_token_here"               # value of the ct0 cookie

)

How Nitter Parses Session Tokens

The session parsing logic in src/experimental/parser/session.nim handles the deserialization of raw JSON into typed Session objects. The parser examines the kind field to determine which authentication variant to instantiate:

1. If kind is empty or "oauth", it constructs an OAuth session with token and secret fields populated
2. If kind is "cookie", it constructs a cookie session with authToken and ct0 fields populated

This unified parsing approach allows Nitter to load either authentication type from configuration files without requiring separate code paths for initialization.

Constructing API Requests with Session Tokens

When issuing authenticated requests, Nitter uses the session kind to determine URL construction strategies. The toUrl method implemented in src/apiutils.nim accepts a SessionKind parameter to build appropriate API endpoints【/cache/repos/github.com/zedeus/nitter/master/src/apiutils.nim†L51-L98】.

let url = testReq.toUrl(SessionKind.oauth)   # for OAuth‑based requests

let url = testReq.toUrl(SessionKind.cookie)  # for cookie‑based requests

This method ensures that OAuth tokens receive the proper signature generation while cookie sessions receive the necessary header configuration for web API endpoints.

Summary

• Nitter defines two session token types in src/types.nim: SessionKind.oauth and SessionKind.cookie
• OAuth sessions use oauthToken and oauthTokenSecret fields for API authentication
• Cookie sessions use authToken and ct0 (CSRF token) fields extracted from browser cookies
• The parser in src/experimental/parser/session.nim handles both types based on the kind field value
• API URL construction in src/apiutils.nim adapts to the session type via the toUrl method

Frequently Asked Questions

What is the difference between OAuth and cookie authentication in Nitter?

OAuth authentication uses API consumer keys and secrets through the OAuth 1.0a protocol, while cookie authentication uses session tokens (auth_token) and CSRF tokens (ct0) extracted from an active Twitter web session. OAuth is the traditional API method, whereas cookie authentication mimics browser behavior and may offer different rate limiting characteristics.

Where are session token types defined in the Nitter codebase?

The session token types are defined in src/types.nim as the SessionKind enum, with the raw JSON structure specified in src/experimental/types/session.nim. The parsing logic resides in src/experimental/parser/session.nim, which converts JSON configurations into typed session objects.

How do I generate a cookie-based session for Nitter?

You can generate a cookie-based session using the tools/create_session_browser.py utility script included in the repository. This script automates browser login to extract the auth_token and ct0 cookies from an authenticated Twitter session, outputting the JSON configuration required for cookie-based authentication.

Which session token type should I use for a private Nitter instance?

Cookie-based sessions (SessionKind.cookie) are often preferred for private instances because they can be generated without API developer credentials and may provide access to certain endpoints not available through standard OAuth. However, OAuth sessions (SessionKind.oauth) remain valid for traditional API access if you possess valid consumer keys and secrets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}