API Sessions

In order for users to write data to their account via the API, we have created a user specific authentication workflow. Upon being completed successfully, the session id that is created can be used to do things like rate movies, add or remove items to a personal watchlist, and also create and edit lists.

The workflow outlined below does not require the transferring or storing of passwords at any point. The user is simply required to log in to their account on our end just like they would in a regular browser. We recommend for extra security, all of this be done over SSL (HTTPS).

Basic Workflow

Step 1: Create a new request token

The first step as a developer is to request a new token. This is a temporary token that is required to ask the user for permission to access their account. This token will auto expire after 60 minutes if it's not used. We strongly recommend using the process outlined in 2a.

Step 2a: Ask the user for permission via the website

The next step is to take the token you got from step #1 and direct your user to the following URL:


This callback URL is also accessible via the Authentication-Callback header that gets returned in step #1. You can also pass in a redirect_to param when making this call which will redirect the user once the authentication flow has been completed.

This step is where the user gets involved, authorizing your API key access to their account.

Step 2b: Ask the user for permission via the API

If you would like to authenticate your request token on the API (as opposed to the webiste method above), you can do so by asking your user for their TMDb username and password.

Please note: that we do not encourage you to use this method as it will transmit a valid username and password combination over tha air. This process should only be used on devices and environments that don't have access to a web browser.

An example of this request looks like:

https://api.themoviedb.org/3/authentication/token/validate_with_login? api_key=API_KEY&request_token=REQUEST_TOKEN&username=###&password=###

Step 3: Create a session ID

Assuming the request token was authorized via step 2a or 2b, you can now go and request a session ID.

The results of this query will return a session_id value. You should treat this value like a password. Store it securely. This is the value required in all of our write methods.

Guest Sessions

Guest sessions are a type of session that doesn't require any user registration. This makes it very easy to help contribute some data back to TMDb. We currently only support the ability to rate movies with a guest session.

You should only issue 1 guest session per user though, as we still treat them as a unique account. In the future there will be the ability to sign up with one of these sessions so users can import all of their rated movies.

You can read the guest session documentation here.