> ## Documentation Index
> Fetch the complete documentation index at: https://samltd-6c86be8d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
Go to [https://www.themoviedb.org/signup](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.
Log in and click your avatar in the top-right corner, then choose **Settings**. In the left-hand sidebar, select **API**.
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.
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.
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:
```bash .env theme={null}
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:
```http theme={null}
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.