Authentication Overview

Netflix API 1.5 Programmer’s Guide: Authentication Overview


To access catalog data (such as information about movies and actors) using Netflix API 1.5, you must have registered your application with Netflix, which gives you the consumer key and shared secret that you use as your authentication credentials (note: no new applications may be registered at this time). To access data for particular Netflix subscribers (such as their instant watch queue and title ratings), each subscriber must also explicitly grant your application access. This page describes how your application gets these authentication credentials and presents them to Netflix API 1.5.

The authentication process achieves these important goals:

  • Netflix subscribers never have to reveal their login credentials to anyone who isn’t Netflix.
  • Netflix subscribers can instantly revoke access permissions to any individual application without having to change their Netflix password.
  • Netflix resources are used only by developers who play by the rules.

Netflix API uses the OAuth authentication method.

Before You Go Any Further

If you are a registered developer, please go try out the Netflix Authentication Walk-Through. This tutorial will take you from your first token request all the way through adding, changing, and deleting a subscriber’s Netflix instant watch queue items, without you needing to write any code. You may also find it useful to refer back to this tutorial later if you run into trouble understanding how to sign Netflix API calls or make API requests. You will need a Netflix subscriber account, either your own or a test account, to complete all of the steps in the walk-through.

Netflix API Requests

There are three security levels of API requests, each requiring its own process of authentication:

Non-Authenticated Requests (Consumer Key only)
For these API requests, you only need to demonstrate that you’re a registered developer by providing the consumer key that you received when you registered your application. Examples of non-authenticated calls are the Netflix API’s autocomplete title search and the Netflix JavaScript API.
Signed Requests (Consumer Key + Signature)
For these API requests, you must generate a cryptographic signature based on your request, your consumer key, and your shared secret. Most Netflix API catalog requests (searches or data retrieval about titles, cast members, and such) require this sort of signature.
Protected Requests (Consumer Key + Signature + Subscriber Access Token)
For API requests that access Netflix subscriber data, you must also prove to the Netflix API that the subscriber has explicitly granted your application this access. Once the subscriber grants your application access, the Netflix API will carry out your requests on the subscriber’s behalf until such time as the subscriber revokes your access permission. These requests must be signed like those in the previous category (though with a signature that is generated with both your shared secret and a token secret), and must also contain an access token.

The following table shows the various resources in the Netflix API and what variety of credentials you need to present when you request each resource:

Resource Authentication Variety Notes
catalog/titles/autocomplete non-authenticated
all other catalog/titles resources signed or protected
catalog/people resources signed or protected
users/ resources protected
oauth/request_token signed or protected
oauth/login unsigned https to
oauth/access_token protected
oauth/clock/time unsigned https

The following sections of this page show you how to make each of these varieties of API request:

  1. Making Non-Authenticated Requests
  2. Making Signed Requests
  3. Making Protected Requests

API Request Limits

Calls to the Netflix API are limited as follows:

  • Your application can make no more than ten requests per second
  • Your application can make no more than 25,000 signed requests per day
  • Your application can make no more than 25,000 protected requests per subscriber per day

Because you can make 25,000 protected requests per subscriber per day, but only 25,000 signed requests total per day, it makes sense for you to encourage the users of your application to sign in with their Netflix credentials so that you can make protected requests on their behalf rather than using up requests from the shared signed request pool.

NOTE: You can always make either a signed or a protected requested to a resource that only requires a signed request. If you have the ability to make a protected rquest, you should make it in favor of a signed request, so that you do not use up your signed request quota.

Making Non-Authenticated Requests

You can access the JavaScript API, the autocomplete catalog search, and the time-sync resource without having to authenticate your request with a signature. As a warmup exercise, let’s try out the autocomplete feature:

Copy the line above, paste it into any browser, but substitute your application’s consumer key for the bit that says YourConsumerKey. You should get back something substantially similar to this:

<?xml version="1.0" standalone="yes"?>
  <title short="Frances McDormand">

If your consumer key is not working, you’ll get this:

Missing Required Consumer Key

If so, please go back to the My Account page and make sure you’ve copied your key correctly.

Things to Do and Notice

  • With this request, you asked the Netflix API to look for a specific term, "frances mc". In the URL that contained the request, you had to "percent encode" the space between frances and mc by converting it to "%20" (this page will explain percent encoding in more detail below).
  • The response from the Netflix API came back with a helpful url_template element that shows you which request parameters will work with this variety of Netflix API request. In this case, the only parameter is term. The part that reads -join|& shows up in the url_template for all Netflix API requests, and indicates that you can send multiple parameters in one request as long as you delimit them with an ampersand.

Making Signed Requests

The OAuth authentication process is complicated, especially for beginners. Fortunately, there are libraries available for many programming languages that do most of the difficult parts for you. For best results, take it one step at a time.

NOTE: Kent Brewster’s Netflix Catalog API Explorer is a tutorial that walks you through the process of making signed catalog requests, and will sign your request with your key and secret and show you the response from the Netflix API.

This page describes in detail how to sign a request, but in practice you will probably use library calls that hide much of this complexity.

Creating Signatures

Throughout your OAuth experience, you’ll be “signing” various Netflix API requests:

VERB  … &parameterN=value&oauth_consumer_key=your_key&oauth_nonce=nonce&oauth_signature_method=HMAC-SHA1&oauth_timestamp=timestamp&oauth_version=1.0&oauth_signature=signature

The components of such a request are as follows:

one of the HTTP verbs (for requests of this kind, usually GET)
the path indicates which specific Netflix API request you are making
each Netflix API request has a set of (usually optional) parameters that modify how it works or what data it retrieves
your application’s public key, listed simply as “key” on your developer profile
a random string of characters that differs from call to call (this helps to prevent replay attacks)
be sure to make these characters legal to percent-encode or include in URLs
the number of seconds elapsed since midnight, 1 January 1970. Be sure this is within ten minutes of the real time, and also please understand that client-side apps will be at the mercy of their system clocks, and will fail with bad timestamp errors if they’re too far off. You can get the current timestamp that the Netflix API is using by calling
(optional) if you include this, you must set it to "1.0" (which is also the default). We will be including it throughout this page and think you should too, to help you keep in mind that the OAuth spec is a living document, and will undoubtedly be updated in the future.
you generate the signature by passing into a cryptographic function your consumer key, your shared secret, and an encoded version of the "base string" (the part of the request shown in green above)

Note: You never include your shared secret directly as one of the parameters. The Netflix API has your shared secret on file. It authenticates you by running your request backwards through the same cryptographic function you used to generate the signature in order to verify that you used your shared secret to generate the request. If so, the Netflix API assumes that the request is really coming from you and has not been tampered with.

Percent Encoding

Much of the trouble people run into with OAuth centers around percent encoding, also called URL-encoding.

  • You always must percent encode certain characters in URLs.
  • You must percent encode certain characters in the base string that you send to the cryptographic function with which you generate your signature.

You percent encode a character by converting it to a string consisting of its two-digit hexadecimal representation prefixed with the "%" character. The characters that you must encode in this way are the space character ("%20") and those in the following list:

! * ' ( ) ; : @ & = + $ , / ? % # [ ]

After percent-encoding, they look like this:

%21 %2A %27 %28 %29 %3B %3A %40 %26 %3D %2B %24 %2C %2F %3F %25 %23 %5B %5D

NOTE: The percent-encoded representations must be capitalized in the version of the base string that you pass into your cryptographic function. In other words, "%3B" is okay but "%3b" will fail. Caution: some .NET libraries don’t get this right.

You must not percent encode any other characters. Other characters that are allowed in the URL include the upper- and lower-case letters A through Z, the numbers 0 through 9, and the dash, underscore, period, and tilde characters.

Other characters not mentioned above — carats and pipe-signs and backslashes, for example — are forbidden, and you must not use them in URLs, percent-encoded or otherwise

JavaScript’s encodeURIComponent( ) function won’t catch them all. You’ll need to write a custom function that replaces exclamation marks, asterisks, single-quotes, and parentheses. Here is the function Netflix uses in its Netflix Authentication Walk-Through tutorial:

function oAuthEscape(r) {
  return encodeURIComponent(r).replace("!","%21","g").replace("*","%2A","g").replace("'","%27","g").replace("(","%28","g").replace(")","%29","g");

Constructing the Base String

The base string is one of the elements you feed into the function that generates the signature for your request. The base string is that part of your Netflix API HTTP request that is shown in green in the description earlier on this page, that you convert into a string by using the rules described in this section. This string must include exactly three elements, separated by exactly two unencoded ampersands, like this:

GET, POST, PUT, or DELETE. (For this sort of request, you will almost always use GET or POST)
the string "http[s]://" followed by the path that specifies the particular Netflix API request, percent encoded so that you replace the ":" and "/" characters in the URL with "%3A" and "%2F" respectively
this is the entire request parameter string that appears after (not including) the "?" in the URL (or in the case of POST requests, everything in the request body), except for the oauth_signature parameter itself
these parameters must be listed in ascending alphabetical order in this string, delimited with "&" characters
you must percent encode this string as a whole, including those "&" characters


Our first working example is a catalog query. In this example, you will ask the Netflix API to return a list of people (cast members, directors, and such) who match the query string "frances". To do this, you will query the /catalog/people request with two request parameters:

  • term=frances
  • max_results=10

Because max_results comes before oauth_consumer_key and term=frances comes after oauth_timestamp, your OAuth parameters will show up in the middle of your request parameters when you alphabetically sort them. Your encoded base string would look something like this:


Things to Do and Notice

  • There are exactly two non-encoded ampersands in the encoded base string, one after the GET and one after the request URL. All the other ampersands in the request string are percent-encoded.
  • The "%26" and "%3E" in the request string represent the ampersands and equals signs that separate the parameter names and their values.
  • All parameters in the request string are in alphabetical order.

Signing the Base String

If you are using a library, once you have created your base string, it is easy to generate the signature. You pass your base string and your shared secret to a function and get the signature back. See the OAuth Code Page for examples.

Important: You only need the shared secret when you generate the signatures you use to sign the requests described in this section of the page. For protected OAuth requests you must generate the signature by using a pair of secrets: your shared secret and the authorized token secret. When you pass such a pair of secrets to the function you use to generate those signatures, you separate the secrets with an ampersand ("&") character. In the requests in this section, you do not need to use an authorized token secret, but you put a "blank" secret in its place, which means that you still must put an ampersand after your shared secret. The two valid secret formats are:

  1. YourSharedSecret&AuthorizedTokenSecret
  2. YourSharedSecret&

Also Very Important: don’t percent-encode your secret, or the ampersand between the two secrets. Your secret never leaves your control, so it doesn’t need to be encoded. If you do encode it, your OAuth call will not work.

Why Your Signature Isn’t Always the Same Length

The HMAC-SHA1 function that generates your signature should produce a binary string containing exactly 20 ASCII characters, like this:


But many of these characters cannot be sent as part of an URL, since they are reserved or forbidden. So the binary string will probably emerge from your library call in base-64 format, like this:


Unfortunately, some of these characters also can’t be sent as part of an URL, so they need to be percent-encoded before you make your HTTP request, like this:


Making the Request

When you make your HTTP request, use your original base string (without all of the percent-encoding of the "://", "?", and "&" characters you did when you passed the base string into the signature-generating function), and append the signature to it, like this:

Things to Do and Notice

  • Alphabetical order of the parameters is not important when you send the final query.
  • Be careful to percent-encode your query values, especially whatever you’re sending for the value of oauth_signature. As noted above in Why Your Signature Isn’t Always the Same Length, if it comes back from your HMAC-SHA1 function in base-64 format, chances are pretty good that it contains reserved characters that require encoding.

Having Trouble?

If you’re seeing 400 or 401 errors, something’s wrong at your end. Here are some possibilities:

Error code 400, "Bad Request."

  • You’re sending a parameter name that the Netflix API doesn’t like.
  • You’re trying to use a parameter that the Netflix API doesn’t support.
  • You’re using an unsupported signature method, instead of HMAC-SHA1.
  • You’re missing a required parameter, like oauth_signature.
  • You’re sending two values for the same OAuth parameter.

Error code 401, "Unauthorized."

  • Your key is missing or invalid.
  • You’re re-using a previously-used nonce, or sending a nonce containing invalid characters.
  • Your signature is invalid.

If you’re seeing a bunch of invalid signature errors but you are positive you’re using the right key and secret, something’s probably wrong with your percent-encoding. Please go back to Constructing the Base String and check that you are encoding everything properly, separating the string with two non-encoded ampersands, and sorting all your parameters into alphabetical order before constructing the signature.

If after this you are still having trouble, and are stubbornly refusing all advice to use a pre-existing OAuth library, please read True OAuth Confessions, or Why My Hand-Rolled Calls All Blew Chunks, by Kent Brewster.

Other Things That Might Help

Making Protected Requests

When you make Netflix API requests concerning a particular Netflix subscriber, for instance to read or modify their queues or ratings, you must do so in the form of a protected request. You should understand the process described in the previous section, on signed requests, before reading this section which builds on what you have already learned there.

This is the process of making a protected request:

  1. You send a signed request to the Netflix API that tells the API that you are about to send over a Netflix subscriber who wants to give your application permission to access his account.
  2. The Netflix API verifies the signature on your request and sends your application a request token and a token secret.
  3. Your application then creates a special one-time-only link for your subscriber to click, that includes the request token, your consumer key, your application’s name, and where you want us to send your subscriber once he’s signed in.
  4. If the subscriber clicks this link, Netflix will show him a secure login page on its domain (this way, he only has to give his password to Netflix, never to a third-party. The login page will warns the subscriber that he is about to grant your application access to his Netflix account, lists some of the bad things that might happen if your application is hostile or broken, and gives instructions for how the subscriber can revoke this access. If the subscriber signs in and you’ve told us where to send him, we will send him to the callback page you specified in step 3. (If you haven’t given us a callback, the subscriber will need to find his way back to your page himself.)
  5. When the subscriber lands on your callback page, you’ll make one last request, using your consumer key and consumer secret, and the request token and token secret you received in step 2.
  6. If everything checks out, the Netflix API will send you an authorization token, an authorization token secret, and a user id. These, along with your existing consumer key and shared secret, are your keys to your subscriber’s account. They will remain valid until such time as the subscriber revokes your access, so if you store these keys securely you won’t have to go through this process again the next time the subscriber accesses your application.

Get Your Request Token

The first step in this process is for you to ask the Netflix API for a request token, a token secret, and a URL that your Netflix subscriber can use to grant you access to his account. This is a signed request, that you make by using the process described in the previous section of this page, and that will look something like this:


If successful, the response you get will include:


This is your unauthorized request token, token secret, and the application name you specified when you signed up. (If you ever need to change this name, you may do so from the My Applications page.)

Note: If your application name contains spaces, these will come back from the initial call to oauth/request_token as plus-signs instead of spaces. In subsequent Netflix API calls, you must send your application name exactly the way it comes back in this response, with plusses instead of spaces, or your requests will fail.

Ask the Subscriber to Sign In

Next, you’re going to send the subscriber to our login page to sign in. You form the link to this page by using your application name and consumer key, plus the oauth_token you received in the previous step. You are also going to give us the callback URL you want us to send your subscriber back to after he registers, as oauth_callback.

Here’s a sample URL:

This request is not signed with anything (it’s being made via https, so signing isn’t necessary). Note also the different domain for this request:

When the subscriber signs in successfully, he’ll be redirected back to the callback you specified. This request will look like this:

Important: You can not reuse a request token for more than one login and access token request. That means if the user doesn’t log in within 10 minutes, fails to log in properly, or if you try fetching their access token before they log in, you’ll have to get a new request token and start the process from scratch. If you attempt to reuse a now invalid request token, you’ll get an "Invalid Token" error.

Send Us the Subscriber’s Authorized Request Token

When your callback page receives the subscriber’s authorized request token, you’ll be able to use it to tell us that he’s actually signed in to your application by sending us a request like the following:

You generate the signature for this request using a secret that contains both your application’s shared secret and the oauth_token you received at the end of the previous step. Pass this secret to your signature-generating function in the format "YourSharedSecret&YourAuthorizedToken".

Netflix Checks Things Over

At this point, the Netflix API double-checks your credentials to ensure:

  • the request signature matches the request
  • this request token has never been exchanged for an access token before
  • the consumer key you sent makes sense with the secrets you’re using to sign it

If all of these conditions are true, the Netflix API will send you back a new, authorized oauth_token, a new oauth_token_secret, and a user_id, like this:


Store these in a safe place; they are good until such time as the subscriber revokes your access to his account.

Your First Subscriber Request

Now you can make your first request on behalf of the Netflix subscriber. To do this you’ll need:

  • The subscriber’s user_id (that you received in the previous step) with which you will form your request’s base URL, which looks like this:
  • The authorized oauth_token and oauth_token_secret, which were also given to you in the previous step.
  • Your own consumer key and shared secret, which you’ve been using all along.

You must sign each such request with a combination of your shared secret and the oauth_token_secret. As above when you sent us the subscriber’s authorized request token, you must separate the two secrets with an ampersand when you pass them to your signature-generating function.

You may already know your subscriber’s user_id, but for simplicity’s sake this example will show you how to request that ID by using the Netflix API’s users/current resource. This resource is necessary for OAuth libraries that don’t support standard response extensions, so you may wind up using it quite a bit.

If you sign the request with the full authorized signature, users/current will return the subscriber ID of the subscriber whose authorization is reflected in that signature. To do this, send the Netflix API a request like this:

The Netflix API will respond by sending you back something like this:

 <link href=""
       title="current user">

NOTE: When you retrieve a user ID like this, you should cache it for future use, as you will use it in a variety of calls and it remains valid until such time as the subscriber revokes access permission to your application.

Your Basic User Dump

The href contents in the <link> element above are the base URL that you’ll need to query all other resources on behalf of this Netflix subscriber. You can also create this without doing the user-dump request if your OAuth library is smart enough to accept the user_id parameter you received from the oauth/access_token response.

Here is how to request basic information about a subscriber:

The Netflix API will return something like this:

<?xml version="1.0" standalone="yes"?>
  <category scheme="" label="Instant" term="Instant"></category>
 <link href="" rel="" title="queues"></link>
 <link href="" rel="" title="recommendations"></link>
 <link href="" rel="" title="title states"></link>
 <link href="" rel="" title="ratings"></link>

Other Queries

Your application can plug any of the link href values in the above response back into the API and request them to get additional data. Here (without any of the necessary OAuth parameters) is how to view movies recommended by Netflix to the subscriber:

Many more calls are documented in the User Resources section of the Netflix REST API Reference.

Creating, Updating, and Deleting Queued Items and Ratings

These calls are also thoroughly documented in Managing a Queue and User Title Ratings; the only difference between reading items and writing or deleting them is the HTTP verb. You’ll use POST to create new queue items and ratings, and will either use DELETE or set the method parameter to delete to remove them.

Get the Latest ETag

Because more than one application may be accessing a subscriber’s data at the same time, it is important that before you make any modifications to this data you verify that you are not working with stale data.

To facilitate this, each time you make a Netflix API call that modifies or deletes subscriber data, you must submit an ETag that corresponds to the most recent version of that data you have accessed. Each time you make a Netflix API request for subscriber data, the API will return such an ETag to you in the response, in an <etag> element:


You need a fresh ETag for every write, update, or delete request. If the ETag you submit with your request matches the one that the Netflix API generated the last time the record in question was modified, your request will go through. Otherwise, the Netflix API will inform you that you are working with stale data.

Add an Item to a Subscriber’s Queue

To add an item to a subscriber’s queue, submit a request like the following:

Because this is a write request rather than a read request, you must use POST as your HTTP verb when you sign and send this call, not GET. If you make your request with GET, you’ll see the user’s queue as your response, but will not successfully modify it. If your add was successful, you’ll see something like this:

<?xml version="1.0" standalone="yes"?>

Move a Queue Item

In this case, let’s say the movie wound up in queue position 25. Using the FreshEtag from the previous return, you can sign and POST a new request like the following to move it up to position #3:

Here’s what comes back when we move “A Night at the Opera” to position #3:

<?xml version="1.0" standalone="yes"?>
 <message>Move successful</message>


Notice that this request used the FreshETag from the response to the previous request and used it for the request’s etag value. The response came back with AnotherFreshEtag that you could then use in your next call.

While it’s theoretically possible to add a movie directly to the top of a subscriber’s queue, using position=1 with the initial add, we strongly suggest you do not do this, since subscribers really hate it when their queues don’t behave the way they’re used to.

Remove a Queue Item

To remove the item that you added and moved in the previous two examples from the subscriber’s queue, copy AnotherFreshETag from the return above, then sign and POST the following request:

Remember, to delete from within a Web browser, you’ll need to overload method by sending method=delete as part of your POST request. (Browsers don’t have access to DELETE under the HTTP spec. If you are making this call with a non-browser-based application, feel free to use the DELETE verb, in which case you can omit the method parameter.)

Here’s your return:

<?xml version="1.0" standalone="yes"?>
 <message>Title deleted from queue</message>

What Now?

Many more calls are documented in the User Resources section of the Netflix API 1.5 Reference.