Pocket


The Pocket Authentication API uses a variant of OAuth 2.0 for authentication. OAuth 2.0 is meant to be straightforward to implement, and also provides increased security for user authentication because 3rd party client apps no longer need to request or store a user's login information to authenticate with Pocket.

Note for iOS/Mac Developers: If you are building an iOS or Mac app, the Pocket Objective-C SDK handles all of the OAuth authentication for you and is the fastest way to add Pocket integration to any app.

General Guidelines

  • All calls to the Pocket Authentication API should be done over HTTPS.
  • All calls to the Pocket Authentication API should be POST - we do not support GET.
  • The Content-Type header indicates the format of your request. This includes the type of data (e.g. JSON or form-urlencoded) and the character set (e.g. UTF8).
    • The Pocket Authentication API supports two formats:
      • application/x-www-form-urlencoded (DEFAULT)
      • application/json
    • You must also pass the character set after the format, separated by a semicolon. The HTTP 1.1 specification states the default for this is ISO-8859-1, which is probably not what you want. For example, a full header for UTF8-encoded data would look like one of these:
      • Content-Type: application/x-www-form-urlencoded; charset=UTF8
      • Content-Type: application/json; charset=UTF8
  • The X-Accept header indicates the format you would like to receive the response, the Pocket Authentication API supports two formats:
    • application/x-www-form-urlencoded (DEFAULT)
    • application/json

Step 1: Obtain a platform consumer key

Registering your app with Pocket associates it with a platform consumer key. This key identifies your app to Pocket's API.

If you have not obtained a consumer key yet, you can register for one at http://getpocket.com/developer/apps/new.

A Pocket consumer key looks like: 1234-abcd1234abcd1234abcd1234

Important note: If you have a previous apikey from Read It Later/Pocket - that will no longer work. You will need a new consumer key.

To begin the Pocket authorization process, your application must obtain a request token from our servers by making a POST request.

Method URL:

https://getpocket.com/v3/oauth/request

Parameters
consumer_key string The consumer key for your application (see Step 1).
redirect_uri string The URL to be called when the authorization process has been completed. This URL should direct back to your application. See the Platform Specific Notes section for details about setting up custom urls for the redirect_uri on iOS and Android.
state string optional A string of metadata used by your app. This string will be returned in all subsequent authentication responses.

Important note: In all the examples that follow, some HTTP headers have been removed to simplify the display.

POST /v3/oauth/request HTTP/1.1
Host: getpocket.com
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Accept: application/x-www-form-urlencoded consumer_key=1234-abcd1234abcd1234abcd1234&
redirect_uri=pocketapp1234:authorizationFinished
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
Status: 200 OK code=dcba4321-dcba-4321-dcba-4321dc
POST /v3/oauth/request HTTP/1.1
Host: getpocket.com
Content-Type: application/json; charset=UTF-8
X-Accept: application/json {"consumer_key":"1234-abcd1234abcd1234abcd1234",
"redirect_uri":"pocketapp1234:authorizationFinished"}
HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK {"code":"dcba4321-dcba-4321-dcba-4321dc"}

This request token (the "code" in the response) must be stored for use in step 5. For web applications, it should be associated with the user's session or other persistent state.

If the HTTP status of the response is 200, then the request completed successfully. Otherwise, an error occurred. When there is an error, the HTTP Header will contain details of the error using three fields: HTTP Status Code, X-Error-Code and X-Error.

HTTP Status X-Error-Code X-Error
400 138 Missing consumer key.
400 140 Missing redirect url.
403 152 Invalid consumer key.
50X 199 Pocket server issue.

Step 3: Redirect user to Pocket to continue authorization

Once you have a request token, you need to redirect the user to Pocket to authorize your application's request token.

When redirecting the user, you need to include two pieces of information: (1) the request token you received in Step 2; and (2) the redirect_uri. As a reminder, the redirect_uri is the URL to be called when the user has completed the authorization within Pocket. This URL should direct back to your application.

There are two ways to redirect the user to Pocket:

  1. If you are on iOS and are able to detect the presence of the URL scheme pocket-oauth-v1, you should redirect the user to the Pocket app like this:

    pocket-oauth-v1:///authorize?request_token=YOUR_REQUEST_TOKEN&redirect_uri=YOUR_REDIRECT_URI

    Example using above:

    pocket-oauth-v1:///authorize?request_token=dcba4321-dcba-4321-dcba-4321dc&redirect_uri=pocketapp1234:authorizationFinished

  2. If you are on any other platform -or- are not able to detect the URL scheme, you redirect the user to the Pocket web site like this:

    https://getpocket.com/auth/authorize?request_token=YOUR_REQUEST_TOKEN&redirect_uri=YOUR_REDIRECT_URI

    Example using above:

    https://getpocket.com/auth/authorize?request_token=dcba4321-dcba-4321-dcba-4321dc&redirect_uri=pocketapp1234:authorizationFinished

If you are using the Pocket web site, two additional notes to be aware of:

  • We have a mobile and desktop version of the authorization page. Our servers will try to detect what type of device the user is using and redirect accordingly. In cases where we do not detect screen size (such as on Windows Phone), you can use ?mobile=1 to force the mobile version.
  • In iOS 9, please modify the SDK to send the user to the URL in the Safari View Controller (using the SFSafariViewController class), rather than the default browser. If the app is running iOS 8 or earlier, opening the URL via the default browser is required. If you would like to present this page in a webview or screen within your application, please contact api@getpocket.com with your request so we can consider making an exception.

Regardless of whether you send the user to the Pocket app or website, one of three things will happen when the user arrives:

  1. If the user is signed in to Pocket and has already approved your app (on this or any other platform): The user will be immediately authenticated and the provided redirect_uri will be called.
  2. If the user is signed in to Pocket, but has not yet approved your app: The user will see an authorization request screen or web page that provides the details of your application and the type of access requested. The user will have the option of accepting or denying the request. Once the user has made their decision, the provided redirect_uri will be called.
  3. If the user is not signed in to Pocket: The user will first be prompted to sign in to their Pocket account. If that account has already granted access to your application (on this or any other platform), the redirect_uri will be called immediately. Otherwise, the user will see the authorization request screen or web page as described above.

Note: During testing, you can clear the tokens associated with your test user, by going to: http://getpocket.com/connected_accounts.

Step 4: Receive the callback from Pocket

When the user has authorized (or rejected) your application's request token, Pocket will return the user to your application by opening the redirect_uri that you provided in your call to /v3/oauth/request (Step 2).

Step 5: Convert a request token into a Pocket access token

The final step to authorize Pocket with your application is to convert the request token into a Pocket access token. The Pocket access token is the user specific token that you will use to make further calls to the Pocket API.

When your application receives the callback to the redirect_uri supplied in /v3/oauth/request (step 4), you should present some UI to indicate that your application is logging in and make a POST request.

Method URL:

https://getpocket.com/v3/oauth/authorize

Parameters
consumer_key string The consumer key for your application (see Step 1).
code string The request token supplied in the code field of the /v3/oauth/request call.
Example request (x-www-form-urlencoded):
POST /v3/oauth/authorize HTTP/1.1
Host: getpocket.com
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Accept: application/x-www-form-urlencoded consumer_key=1234-abcd1234abcd1234abcd1234&
code=dcba4321-dcba-4321-dcba-4321dc
Example response (x-www-form-urlencoded):
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
Status: 200 OK access_token=5678defg-5678-defg-5678-defg56&
username=pocketuser
Example request (JSON):
POST /v3/oauth/authorize HTTP/1.1
Host: getpocket.com
Content-Type: application/json; charset=UTF-8
X-Accept: application/json {"consumer_key":"1234-abcd1234abcd1234abcd1234",
"code":"dcba4321-dcba-4321-dcba-4321dc"}
Example response (JSON):
HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK {"access_token":"5678defg-5678-defg-5678-defg56",
"username":"pocketuser"}

The username of the user represented by the access token is provided for presentation in your UI to convey the username of the authenticated user.

If you optionally supplied a state parameter with the original /v3/oauth/request POST, you will also receive that same value in the response.

If the HTTP status of the response is 200, then the request completed successfully. Otherwise, an error occurred. When there is an error, the HTTP Header will contain details of the error using three fields: HTTP Status Code, X-Error-Code and X-Error.

HTTP Status X-Error-Code X-Error
400 138 Missing consumer key.
403 152 Invalid consumer key.
400 181 Invalid redirect uri.
400 182 Missing code.
400 185 Code not found.
403 158 User rejected code.
403 159 Already used code.
50X 199 Pocket server issue.

Step 6: Make authenticated requests to Pocket

Once you have a Pocket access token, you can make authenticated requests to the Pocket v3 API. To do this, you supply two additional parameters to any API request:

  • consumer_key: Your application's Consumer Key (obtained in Step 1)
  • access_token: The specific user's Pocket access token (obtained in Step 5)
Example request (JSON):
POST /v3/add HTTP/1.1
Host: getpocket.com
Content-Type: application/json; charset=UTF-8
X-Accept: application/json {"url":"http:\/\/pocket.co\/s8Kga",
"title":"iTeaching: The New Pedagogy (How the iPad is Inspiring Better Ways of
Teaching)",
"time":1346976937,
"consumer_key":"1234-abcd1234abcd1234abcd1234",
"access_token":"5678defg-5678-defg-5678-defg56"}
Example response (JSON):
HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK {"status":1}

Best Practices

  • When the user taps a "Login" or "connect with Pocket" button in your application, you should present some UI to indicate that your application is preparing to login and make a request to obtain a request token from Pocket.
  • Native mobile applications should register a unique URI scheme and supply a redirect URI using that scheme if the platform you are developing on supports this setup.
  • If you support multiple platforms (e.g. iPhone, iPad, and Mac OS X), you are strongly encouraged to use separate consumer keys for each. You can set them up in a parent/child configuration, so that your credentials are related. Users who authorize one application will authorize all of them.
  • If you detect the user has a Pocket app installed on their device that supports OAuth login, you are strongly encouraged to send the user to the Pocket app to handle authorization.
  • If you send the user to the Pocket website to handle authentication, you are must not open that web page as a screen or a popup within your application. Instead, open a new page in the user's default web browser. For security purposes, using an in application screen or pop up may result in your Pocket access being disabled.
  • If you are developing an Objective-C application for iOS and/or Mac, you are strongly encouraged to use the Objective-C SDK, which handles all of the authentication calls, stores the OAuth tokens, and notifies when there are errors.

Implementing the Pocket Authentication API on iOS/Mac

If you are building an iOS or Mac app, the Pocket Objective-C SDK handles all of the OAuth authentication for you and is the fastest way to add Pocket integration to any app.

Registering a custom url scheme for your REDIRECT_URI on iOS

Once you have the consumer key for the platform you are supporting, the application must register a URL scheme to receive login callbacks. By default, this is "pocketapp" plus your application's ID (which you can find at the beginning of the consumer key before the hyphen). So if your consumer key is 42-abcdef, your app ID is 42, and your URL scheme will be "pocketapp42".

If your app has no URL schemes, you can copy and paste the block below into your Info.plist, updating it with the app's scheme:

<key>CFBundleURLTypes</key>
<array> <dict> <key>CFBundleURLName</key> <string>com.getpocket.sdk</string> <key>CFBundleURLSchemes</key> <array> <string>[INSERT URL SCHEME]</string> </array> </dict>
</array>

Implementing the Pocket Authentication API on Android

If your app already has sharing functionality using an Intent.ACTION_SEND action, with a text mimeType, then 'Add to Pocket' will automatically appear in the Share Via menu/chooser for any users that have Pocket installed.

Registering a custom url scheme for your REDIRECT_URI on Android:

Once you have the consumer key for the platform you are supporting, the application must register a URL scheme to receive login callbacks. By default, this is "pocketapp" plus your application's ID (which you can find at the beginning of the consumer key before the hyphen). So if your consumer key is 42-abcdef, your app ID is 42, and your URL scheme will be "pocketapp42".

This can easily be done by declaring an intent-filter in your app's manifest file.

If your redirect_uri is 'pocketapp1234:' you would add the following filter to the application that you want to be opened when the authorization page finishes.

<intent-filter> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="pocketapp1234" />
</intent-filter>

Note: In the manifest declaration for scheme do not include a ":" at the end of the scheme.

See the Intent Filter documentation for more information: http://developer.android.com/guide/components/intents-filters.html#ifs