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 GuidelinesRegistering 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 tokenTo 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:authorizationFinishedExample 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-4321dcExample 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 authorizationOnce 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:
pocket-oauth-v1:///authorize?request_token=YOUR_REQUEST_TOKEN&redirect_uri=YOUR_REDIRECT_URI
Example using above:
https://getpocket.com/auth/authorize?request_token=YOUR_REQUEST_TOKEN&redirect_uri=YOUR_REDIRECT_URI
If you are using the Pocket web site, two additional notes to be aware of:
Regardless of whether you send the user to the Pocket app or website, one of three things will happen when the user arrives:
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 PocketWhen 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 tokenThe 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-4321dcExample 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=pocketuserExample 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 PocketOnce 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:
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
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
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.3