Authentication

Learn how to authenticate with the TMDB API using a Bearer token or a v3 API key.

The TMDB client accepts two types of credentials. Pass either one as the first argument to the constructor.

Bearer Token (Recommended)

TMDB's Read Access Token is a signed JWT. This is the recommended way to authenticate because credentials are sent in the Authorization header and never appear in URLs or server logs.

You can find your Read Access Token in the TMDB dashboard under Settings → API → API Read Access Token.

import { TMDB } from "@lorenzopant/tmdb";

const tmdb = new TMDB("eyJhbGciOiJIUzI1NiJ9...");

When a JWT is detected, the client automatically sends:

Authorization: Bearer <token>

v3 API Key

If you have a legacy v3 API key (a plain string without dots), the client appends it as an api_key query parameter on every request.

import { TMDB } from "@lorenzopant/tmdb";

const tmdb = new TMDB("your_v3_api_key");

When a v3 key is detected, the client sends requests like:

GET https://api.themoviedb.org/3/movie/550?api_key=your_v3_api_key

v3 API keys appear in URLs and may be captured in server logs, proxy logs, and browser history. Prefer the Bearer token where possible.

The client inspects the token you pass and checks whether it is a structurally valid JWT (three Base64URL-encoded segments separated by dots with a valid header and payload). No network call is made — the check is purely local.

Token type	Sent as
JWT	`Authorization: Bearer <token>` header
API key	`?api_key=<key>` query parameter

Environment Variables

Store credentials in environment variables — never hard-code them.

.env

# Bearer token (JWT) — recommended
TMDB_BEARER_TOKEN=eyJhbGciOiJIUzI1NiJ9...

# v3 API key — legacy fallback
TMDB_API_KEY=your_v3_api_key

tmdb.ts

import { TMDB } from "@lorenzopant/tmdb";

const tmdb = new TMDB(process.env.TMDB_BEARER_TOKEN!);

User-Level Authentication (Session IDs)

For a deeper explanation of the session flow, see the official TMDB guide: How do I generate a session ID?

The credentials above identify your application to the TMDB API. To act on behalf of a specific user — managing their favorites, watchlists, and ratings — you also need a user-level session_id.

Session IDs are obtained through the AuthenticationAPI and passed as a parameter to account-level endpoints.

v3 Session Flow

This is the standard browser-based flow:

import { TMDB } from "@lorenzopant/tmdb";

const tmdb = new TMDB("your-access-token");

// Step 1 — generate a short-lived request token (expires in 60 minutes)
const { request_token } = await tmdb.authentication.create_request_token();

// Step 2 — redirect the user to approve the token on TMDB
// (this is a browser redirect, not an API call)
const approvalUrl = `https://www.themoviedb.org/authenticate/${request_token}`;
// redirect(approvalUrl); — handle in your app's router

// Step 3 — after approval, exchange the token for a permanent session ID
const { session_id } = await tmdb.authentication.create_session({ request_token });

// Use the session_id with account endpoints
await tmdb.account.add_favorite({ account_id: 123, session_id }, { media_type: "movie", media_id: 550, favorite: true });

Server-Side Flow (no browser redirect)

For server-side apps or environments without a web view, you can skip the redirect step and validate the token directly with the user's credentials:

// Step 1 — create a request token
const { request_token } = await tmdb.authentication.create_request_token();

// Step 2 (server-side) — validate with username and password
const validated = await tmdb.authentication.create_session_with_login({
	username: "johndoe",
	password: "secret",
	request_token,
});

// Step 3 — exchange for a session ID
const { session_id } = await tmdb.authentication.create_session({
	request_token: validated.request_token,
});

Only use create_session_with_login over HTTPS. Prefer the browser-redirect flow when possible to avoid handling user credentials yourself.

Logging Out

To invalidate a session when the user logs out:

await tmdb.authentication.delete_session({ session_id });

Guest Sessions

If you only need rating functionality without a registered account, use a guest session. Guest sessions expire after 60 minutes of inactivity and provide limited capabilities (ratings only — no favorites or watchlists).

const { guest_session_id } = await tmdb.authentication.create_guest_session();

Getting Your Credentials

TMDB API settings — find both your v3 API key and your Read Access Token here.
TMDB Getting Started — official guide.
Authentication API reference — full method documentation.