OAuth Step By Step

Here is a short guide to the process of obtaining access to user-related resources via OAuth. Many of the details should be taken care of by whatever OAuth library you are using - in practice you should only need to configure it with the service configuration parameters specified at OAuth Service Configuration .

The examples below assume a Consumer Key of 2blu7svnhwkzw29zg7cwkydn and a Consumer Secret of tr8up3xbst. Note that these credentials will not work. When you use our API, you must substitute your own key and secret, and you will need to compute the Authorization header correctly based on this - your OAuth library should take care of this for you.

Step 1 - Obtain Unauthorised Request Token

(See also Obtaining an Unauthorized Request Token in the OAuth 1.0A specification)

Make a POST request to http://openapi.lovefilm.com/oauth/request_token, setting the Authorization header correctly, as dictated by the OAuth 1.0A specification. In particular, you should set oauth_callback to one of the following values:

a URL you control, e.g. "http://your-service.com/success"

this indicates that once the user has authorised access to their account on our website, we will redirect their browser back to your service. The user will not need to enter any authorisation tokens manually in this case - they will be passed via URLs. This is appropriate for browser-based services (e.g. websites).

the value "oob"

this indicates that no HTTP redirects will be issued, and that the user will need to manually enter authorisation tokens. This is appropriate for non-browser based services - e.g. set top boxes.

Example request token request:

    POST /oauth/request_token HTTP/1.1
    Host: openapi.lovefilm.com
    Authorization: OAuth
        oauth_callback="http%3A%2F%2Fyour-service.com%2Fsuccess",
        oauth_consumer_key="2blu7svnhwkzw29zg7cwkydn",
        oauth_nonce="5f38dbc02a97567965f14d",
        oauth_signature="sPSVmqN%2FXu9k0wlZxF0PqPZwYGo%3D",
        oauth_signature_method="HMAC-SHA1",
        oauth_timestamp="1278499295",
        oauth_version="1.0"

Example Response

    HTTP/1.1 200 OK
    Content-Length: 143
    Content-Type: application/x-www-form-urlencoded

    oauth_token=SSFMW
    &oauth_token_secret=pnDd3WtHmgpmhp8n32zScPG3
    &login_url=https%3A%2F%2Fwww.lovefilm.com%2Factivate
    &oauth_callback_confirmed=true

The parameters oauth_token and oauth_token_secret are temporary credentials valid for a few minutes. They can only be used to obtain a long-lived "access token", once the user has authorised access to their account.

The parameter oauth_callback_confirmed indicates that we understand the OAuth 1.0A specification. You should only proceed if this parameter is present and set to true.

Step 2 - User Authorises Request Token

(See also OAuth 1.0A - Obtaining User Authorization in the OAuth 1.0A specification)

If your application is browser-based, or can provide a browser:

        https://www.lovefilm.com/activate?oauth_token=SSFMW

If your application is non-browser based, e.g. a Set Top Box:

        To allow us to access your Lovefilm account on your behalf,
        please visit "https://www.lovefilm.com/activate", and enter
        the activation code "SSFMW".

Step 3 - Exchange Request Token for Access Token

(See also Obtaining an Access Token in the OAuth 1.0A specification)

Your application should now have an oauth_token, an oauth_token_secret, and an oauth_verifier. The oauth_verifier will either have been entered manually by the user, or passed in as a query parameter when we redirected the user's browser to your oauth_callback URL.

You can now use these details to obtain an access token.

Make a POST request to http://openapi.lovefilm.com/oauth/access_token, setting the Authorization header correctly, as dictated by the OAuth 1.0A specification. In particular, you should ensure you set oauth_verifier to the value you just received.

Example access token request:

    POST /oauth/access_token HTTP/1.1
    Host: openapi.lovefilm.com
    Authorization: OAuth oauth_consumer_key="2blu7svnhwkzw29zg7cwkydn",
        oauth_nonce="517530e78e2d8aad89bbf5",
        oauth_signature="nwPvclnSRTIkFXdE7kpXHEbks8Q%3D",
        oauth_signature_method="HMAC-SHA1",
        oauth_timestamp="1278503601",
        oauth_token="SSFMW",
        oauth_verifier="682cfdf2a8a6238d5d649b",
        oauth_version="1.0"

Example Response

    HTTP/1.1 200 OK
    Content-Length: 108
    Content-Type: application/x-www-form-urlencoded
    
    oauth_token=6n93somb7slawvnnbtrbfdd1qdn99urtgr5yzuu5f2e3ajtioyaqqako56h1qqru
    &oauth_token_secret=tuKVYdPD4n72

You should now store the returned oauth_token and oauth_token_secret in your application and will need to use them to make requests to the rest of our API on behalf of the user.

Step 4 - Access Protected Resources

(See also Accessing Protected Resources in the OAuth 1.0A specification)

Using the credentials obtained in step 3, your application can now make API calls to resources related to the authenticated user. As usual, you will need to set the Authorization header correctly, as dictated by the OAuth 1.0A specification.

Example protected resource request:

        GET /users HTTP/1.1
        Host: openapi.lovefilm.com
        Authorization: OAuth oauth_consumer_key="2blu7svnhwkzw29zg7cwkydn",
            oauth_nonce="1770556b231c913bc7b038",
            oauth_signature="TflFJqO6knQ5WtLwZgz8Rrhg0fc%3D",
            oauth_signature_method="HMAC-SHA1",
        oauth_timestamp="1278504833",
        oauth_token="6n93somb7slawvnnbtrbfdd1qdn99urtgr5yzuu5f2e3ajtioyaqqako56h1qqru",
        oauth_version="1.0"

Example Response

    HTTP/1.1 200 OK
    Content-Type: application/xml;charset=UTF-8
    
    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <resource>
        <link href="http://openapi.lovefilm.com/users/9D48675C-096F-11DC-BF5A-88D01745CE5C"
            rel="http://schemas.lovefilm.com/user" title="current user"/>
    </resource>