How to Get and Configure Your TMDB API Key

Learn how to obtain a free TMDB API key from themoviedb.org and configure it in the TMDB app to enable live movie and TV show data.

The TMDB app pulls live data — titles, posters, ratings, release dates, cast information — directly from The Movie Database API. To access that data, you need a personal API key that authenticates your requests. Without it, the app cannot fetch any content. The good news is that a TMDB API key is completely free: you simply create an account on themoviedb.org, request a key through your account settings, and paste it into the app’s configuration file. This takes about five minutes and unlocks the full data set powering the app.

Why an API key is required

The Movie Database uses API keys to identify which application is making each request. This lets TMDB enforce fair-use rate limits, prevent abuse, and give developers visibility into their own usage through the TMDB dashboard. Every call the app makes — searching for movies, loading a show’s episodes, fetching a person’s filmography — includes your key as proof of authorization. Without a valid key, the TMDB API returns a 401 Unauthorized error and no data is returned to the app.

Get your API key

1. Create a free TMDB account

   Go to https://www.themoviedb.org/signup and register with your email address. You’ll receive a confirmation email — click the link to verify your account before proceeding.

2. Open your API settings

   Log in and click your avatar in the top-right corner, then choose Settings. In the left-hand sidebar, select API.

3. Request an API key

   Click Create under the “API Key (v3 auth)” section. TMDB will ask you to choose a key type — select Developer for personal or non-commercial use. Read and accept the API Terms of Use.

4. Fill in your application details

   Complete the short application form with a name, description, and website for your project. These fields just help TMDB understand how the API is being used. You can enter your personal site URL or http://localhost:3000 if you’re running the app locally.

5. Copy your API key

   After submitting, TMDB displays your new API Key (v3 auth) — a 32-character hexadecimal string that looks like this:

   a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
   

   Copy this key. You’ll also see a Read Access Token (v4 auth) — a longer JWT-style token used with API v4. Keep both values somewhere safe.

Add the key to the app

The TMDB app reads your API key from an environment variable so the key is never hard-coded into application source files. Create a .env file in the root of the project (next to package.json) if one does not already exist, then add the following line:

.env

REACT_APP_TMDB_API_KEY=your_api_key_here

Replace your_api_key_here with the 32-character key you copied from TMDB. Save the file, then restart the development server. The app picks up the new variable automatically on the next start.

Never commit your .env file to version control. Add .env to your .gitignore immediately. Exposing your API key in a public repository allows anyone to use it under your account, potentially hitting your rate limits or getting your key revoked by TMDB.

How the key is used in API requests

Depending on which version of the TMDB API an endpoint uses, the key is sent in one of two ways.

API v3 — the key is appended as a query parameter on every request:

https://api.themoviedb.org/3/movie/popular?api_key=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

API v4 — the Read Access Token is sent as a Bearer token in the Authorization header:

GET /4/list/1 HTTP/1.1
Host: api.themoviedb.org
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

The app handles this automatically — you only need to supply the REACT_APP_TMDB_API_KEY environment variable.

Your v3 API key and your v4 Read Access Token are two separate credentials, both available on the same TMDB settings page. The v3 key is a short hex string; the v4 token is a long JWT. The app primarily uses v3 endpoints but falls back to v4 for certain account-based features. Configure only REACT_APP_TMDB_API_KEY for the v3 key — the app derives the v4 token automatically from your TMDB session when needed.

Security best practices

• Use environment variables — never paste your key directly into source code, component files, or configuration files that get committed to version control.
• Add .env to .gitignore — do this before your first commit to ensure the file is never accidentally tracked.
• Use .env.example — commit a .env.example file with a placeholder value (REACT_APP_TMDB_API_KEY=) so collaborators know which variables to set without exposing real values.
• Rotate compromised keys — if you accidentally expose your key, go to TMDB Settings → API and regenerate it immediately. Your old key becomes invalid at that point.
• Restrict usage on TMDB — the TMDB dashboard lets you see recent API usage. Monitor it periodically to catch unexpected spikes.

What to expect if the key is missing or invalid

Situation	What you’ll see
REACT_APP_TMDB_API_KEY is not set	The app shows a configuration error banner on launch and no content loads
The key is set but contains a typo	API calls return 401 Invalid API key and the app displays an error state on all data-dependent screens
The key has been revoked by TMDB	Same 401 response; regenerate your key on the TMDB settings page
You’ve exceeded the rate limit	API calls return 429 Too Many Requests; the app retries automatically after a short delay

If you’re seeing errors after adding your key, double-check that you restarted the dev server after editing .env and that there are no extra spaces or quotes around the key value in the file.