Pocket Developer Program: Pocket Authentication API: Documentation

Pocket Authentication API Documentation

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.

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.

Step 2: Obtain a request token

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.

Example request (x-www-form-urlencoded):

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

Example response (x-www-form-urlencoded):

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

code=dcba4321-dcba-4321-dcba-4321dc

Example request (JSON):

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"}

Example response (JSON):

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:

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
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:

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.
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.
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.

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.

Implementing the Pocket Authentication API on iOS/Mac

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:

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

Pocket

Apps

Documentation

Getting Started

Additional Info

Pocket Authentication API Documentation

General Guidelines

Step 1: Obtain a platform consumer key

Step 2: Obtain a request token

Method URL:

Parameters

Example request (x-www-form-urlencoded):

Example response (x-www-form-urlencoded):

Example request (JSON):

Example response (JSON):

Step 3: Redirect user to Pocket to continue authorization

Step 4: Receive the callback from Pocket

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

Method URL:

Parameters

Example request (x-www-form-urlencoded):

Example response (x-www-form-urlencoded):

Example request (JSON):

Example response (JSON):

Step 6: Make authenticated requests to Pocket

Example request (JSON):

Example response (JSON):

Best Practices

Implementing the Pocket Authentication API on iOS/Mac

Registering a custom url scheme for your REDIRECT_URI on iOS

Implementing the Pocket Authentication API on Android

Registering a custom url scheme for your REDIRECT_URI on Android: