Skip to content

Authenticating with the API

David Moore edited this page Jan 30, 2014 · 23 revisions

How It Works

PMP Authentication Model uses OAuth2 Client Credentials flow. In practice this means:

  1. API developer is given a username and password by PMP administration.
  2. Using the user/password developer can generate any number of client credentials: client_id and client_secret. Typically you would want to generate at least one set of credentials for each of your applications.

    It's a bad idea to share client credentials between, say, your web app and iPhone app or your iPhone app and Android app. Each app has different security profile, if one app (client) gets compromised and corresponding client credentials are lost, you wouldn't want to replace credentials in all apps that use the same credentials.

    As an additional security feature you can request credentials that have scope=read. Such credentials (as opposed to: scope=write) are restricted to making read-only requests to the API. It's highly recommended to use read-only credentials for highly insecure environments such as un-authenticated users in web applications.

  3. Application code (typically, through an SDK) uses client credentials to request a temporary authentication token (bearer token) from the API. Once the token is obtained, it is used to make API request that retrieve or update content. Tokens have limited time-span of validity. A proper SDK will automatically re-request new token, once the old one expires.

What You need

To use PMP Authentication API, you need to acquire a user and a password. At the time of writing of this documentation, PMP API is in private beta and user/pass is given directly to the participating partners.

In the following examples, we will assume that the your username/password are: pmpuser and pmpsecret respectively.

Testing Access

To test a connection to the Auth API and see if your user has any credentials assigned yet, make an HTTP GET request to https://api-sandbox.pmp.io using Basic Authentication. CURL command for a thing like that would look like the following:

curl --user pmpuser:pmpsecret \
     -X GET "https://api-sandbox.pmp.io/auth/credentials"   \
     -L -m 5

The response should look something like (actual values redacted):

{
  "clients": [
    {
      "client_id": "…redacted…",
      "client_secret": "…redacted…",
      "scope": "write",
      "token_expires_in": 1209600
    }
  ]
}

Generating credentials

Using the user/password you can also generate new security credentials for your application via the Credentials API endpoint.

Issuing new set of credentials:

curl --user pmpuser:pmpsecret \
     -X POST "https://publish-sandbox.pmp.io/auth/credentials" \
     -d "scope=read" \
     -d "token_expires_in=1380000" \
     -d "label=somethingCool" \
     -L \
     -m 5 \

Should be a HTTP/1.1 200 OK response with json like above, but with only the single new credential.

The response should look something like (actual values redacted):

{
  "client_id": "...redacted...",
  "client_secret": "...redacted...",
  "token_expires_in": 1380000,
  "scope": "read",
  "label": "somethingCool"
}

Note: If you're getting a "400 Bad Request" response for POST requests, try using the "https://publish-sandbox.pmp.io" url, instead of "api-sandbox".

Removing a Credential

Is done by firing an HTTP DELETE on /auth/credentials/{client_id} URI with Basic Auth:

curl --user pmpuser:pmpsecret \
     -X DELETE "https://publish-sandbox.pmp.io/auth/credentials/c3a5a331-ec0a-4273-9d7c-c262295a5542" \
     -L \
     -m 5 \

The response will be an empty payload with: HTTP 204 No Content response code.

Grabbing an Access Token over HTTP

To issue a new token or grab the value of the existing one

POST /auth/access_token

with the HTTP header of:

Content-Type: application/x-www-form-urlencoded
Authorization: Basic YzNhNWEzMzEtZWMwYS00MjczLTlkN2MtYzI2MjI5NWE1NTQyOjUwOTgyMjUwZDdjM2U3ZWE0NDQ3YTFlMg==

Where the long hash is base64-encoded, colon-separated client_id, client_secret. Example code in PHP:

<?php
$hash = base64_encode("c3a5a331-ec0a-4273-9d7c-c262295a5542" . ":" . "50982250d7c3e7ea4447a1e2");

The request must also include form-urlencoded parameter of:

grant_type=client_credentials

Grabbing an Access Token Using the SDK:

<?php
require_once(dirname(__FILE__).'/phpsdk/lib/Pmp/Sdk/AuthClient.php');

$host = 'https://api-sandbox.pmp.io';
$client_id = "…redacted…";
$client_secret = "…redacted…";

$auth = new \Pmp\Sdk\AuthClient($host, $client_id, $client_secret);

print_r($auth->getToken());

exit(0);

Should give a response that looks something like the following:

stdClass Object
(
    [access_token] => 6be3161734dcbd1184cab9d9
    [token_type] => Bearer
    [token_issue_date] => 2013-09-30T20:20:14+00:00
    [token_expires_in] => 1209296
)

Using Access Token to Make API Calls

To make API calls in PMP, a client must set two HTTP headers:

Authorization: Bearer xxxxxxxxxxxxxx
Content-Type: application/vnd.pmp.collection.doc+json

where you replace xxxxxxxxxxxxxx with the token acquired from the authorization server.

Something went wrong with that request. Please try again.