Create A Developer Portal Account

In order to use the PFLlink API, you need to be a registered developer with PFL. Registration is free and takes only a few minutes. With a Developer Portal account, you will be able to:

1. Subscribe to the PFLlink API
2. View the API Reference documentation
3. Submit your Application to the PFLlink Application Gallery
4. Submit Issues and Bugs

Account Creation Steps

1. Visit the Developer Portal at https://portal.pflapi.com

2. Click the “Sign Up” button
   

3. Enter your Email Address, Password, First Name, and Last Name into the registration form and hit “Sign Up”
   

4. A verification email will be sent to your email address.
   
   Wait for the email to arrive and click the appropriate “Confirm” link.
   
   If the email doesn’t arrive, you can choose to resend it. Additionally, be sure to check your junk email folder.

5. Congratulations; you now have an account. The system will take you to your developer profile page where you can manage your basic identity information, and any API subscriptions you’ve signed up for. Initially, this list will be blank; the next step is to get a subscription to one of the PFLlink API collections.
   

NOTE:
The Your applications list contained in the Profile page represents listings in the PFLlink API Application Gallery; these are Content-management system type listings and are not tied to any API behavior or permissions. These are not registered “Services” that have a Client Secret and Client Key and can make authenticated API calls.

Subscribe To An API Collection

The PFLlink Developer Portal exposes multiple PFL API’s to third-party developers. These individual API’s are grouped into Products. Additionally, usage restrictions such as rate limits and quotas may be applied to a Product. (Elsewhere in the documentation, 'products' refers to the contents/collection of a store. Here it is a specific developer portal usage referring to an API collection.)

A Developer gains access to a Product by Subscribing to it. Some subscriptions are effective immediately while other require approval by a PrintingForLess.com administrator. (The required approval has been removed from the AppCenter - Premium product, which is the recommended API to subscribe to.) When a subscription is created, the Developer is given a pair of Subscription Keys. All requests to the PFLlink API’s must be accompanied by a valid Subscription Key or the request will be rejected with a HTTP 401 Access Denied response.

Note:
The Subscription Key does not provide any authentication to API resources on its own; requests must also include an OAuth2 token for resource authentication.

Subscribing to a Product

To subscribe to a product, you need to be logged in to the PrintingForLess Developer Portal at https://portal.pflapi.com.

Choose Product from the top navigation. (The direct link to the product page is https://portal.pflapi.com/products). From the products page, choose the product you would like to subscribe to and follow the remaining steps through :

Including the Subscription Key in API Requests

Each API request must include a Subscription Key. The key can be passed through any of the following methods:

• As a URL GET parameter
  Include a GET parameter with a key of “subscription-key” with a value equal to your subscription key.

• As a HTTP Header parameter
  Include an HTTP Header named “Ocp-Apim-Subscription-Key” with a value equal to your subscription key.

Create a PFL User in the PFL Identity Server

The PFLlink Identity Server provides a centralized identity solution for all current and future PFLlink API and Portal functionality. Authentication Tokens (OAuth 2.0) are issued by this server. These tokens are required for accessing most PFLlink API resources.

Through their identity in the PFLLink Identity Server, a PFL User is associated to one or more PFLlink stores. Using the PFLlink API, the user can access these stores to view products, get quotes and submit orders.

3rd Party Applications are registered with the PFL Identity Server (see Register An Application) as authorized applications. Once registered, a 3rd Party Application can request OAuth tokens for PFL Users and then access API resources on their behalf.

For more information on OAuth 2.0 and the authentication process, see Authentication.

PFL User

A PFL User is a person who has access to one or more PFLlink stores. They exist as a record in the identity server and can be created through the PFLlink API. Additionally, they can be associated to PFLlink stores through the API.

Creating a PFL User

A PFLlink user is created by sending a POST request to the /user endpoint of the PFLlink API (see /user) (or by registering as a user of this portal).

As with all API calls, a Subscription Key is required. If you don’t have a Subscription Key, see Subscribe To An API Collection. This particular method does not require an OAuth Token.

To create a user send a POST request to the /user endpoint

Request:

POST /API/v1/user HTTP/1.1
Host: pflapi.com
Content-Type: application/json
ocp-apim-subscription-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Cache-Control: no-cache

Response:

#!json
{
        "Username": "string",
        "FirstName":"string",
        "LastName": "string",
        "Email": "string",
        "Password": "string",
        "Phone": "string"
}

NOTE:
When first created, a User is not associated to any stores. You must add them to a store before they will have access to any store resources.

Note on Username

The following restrictions apply to usernames:

• must not contain an @ symbol (ie. It can’t be an email address)

Get PFL User identity data from an OAuth Token

When calling the PFLlink API, it is important to know which user the access token applies to, and what stores they are associated with.

You can get user identity information by sending an HTTP GET request to the /user endpoint; the request should include the access token in the Authorization header as a bearer token.

Request:

GET /API/v1/user HTTP/1.1
Host: pflapi.com
Content-Type: application/json
ocp-apim-subscription-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Authorization: Bearer XXXX
Cache-Control: no-cache

Response:

#!json
{
        "ID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "Username": "XXXX",
        "UsernameWithDomain": "XXXX@pflportal.com",
        "FirstName": "Bruce",
        "LastName": "Wayne",
        "Email": "bruce@wayne.co",
        "Phone": " 444-555-5555"
}

Additionally, you can get information on the Roles/Permissions granted to the user for various stores by using the /user/roles endpoint.

Request:

GET /API/v1/user/roles HTTP/1.1
Host: pflapi.com
Content-Type: application/json
ocp-apim-subscription-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Authorization: Bearer XXXX
Cache-Control: no-cache

Response:

#!json
[
  {
        "ID": 21,
        "ApplicationID": null,
        "StoreID": "140158",
        "UserID": "9a0372d5-f464-4409-a816-58ff84f08e5d",
        "Grant": "order.self.write"
  }
]

Associating a PFL User to a store

A user has access to one or more PFL stores. In order to call an API operation against a store (GET Products, POST Order, GET Status), the user must be associated to that store. A PFL employee (typically the PFL Account Manager) will need to make the user to store association. The context of the user is tied to the OAuth token.

Through the API, a User can be associated to a store using the store’s Invite Key. The Invite Key is a shared secret key associated with a PFL store; it is provided to the PFL User by their PFL Account Manager.

The Invite Key will typically take the form of a GUID value. For example:

• 04792156-ff07-464e-9445-afc97d062c98
• 37931d58-d994-43a8-9bb3-d6e28079cff6
• c363f650-74b5-45db-98fe-464fbb2c7e15

An Invite Key can only be used once; the first use of the key will grant the User “admin” rights against the store. Subsequent users must be added by the “admin” User. This can be done either through the /store/{ID}/user endpoint (current), or through the PFLlink Portal (future).

To associate the user to a store, send an HTTP POST request with the user’s OAuth token and the Invite Key to the /store/invite endpoint. The token is sent in the Authorization header as a bearer token.

Request:

POST /API/v1/store/invite HTTP/1.1
Host: pflapi.com
Content-Type: application/json
ocp-apim-subscription-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Authorization: Bearer XXXX
Cache-Control: no-cache
{
  "InviteKey": "f48f0957-ac71-43b5-8155-beb4bd84f33a"
}

Response:

#!json
{
        "StoreID": "string",
        "BudgetEnabled": true,
        "BudgetTypes": [
    {
        "Value": "string",
        "Description": "string"
    }
  ],
        "BudgetDuration": [
    {
        "Value": "string",
        "Description": "string"
    }
  ],
        "CompanyName": "string"
}

Using the Demo Store

A Demo store is available for tesing purposes. The Demo store has limited permissions and a small selection of products.

To associate a User to the Demo store, use the /store/invite method (see above) with an Invite Key value of demo

Request:

POST /API/v1/store/invite HTTP/1.1
Host: pflapi.com
Content-Type: application/json
ocp-apim-subscription-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Authorization: Bearer XXXX
Cache-Control: no-cache
{
  "InviteKey": "demo"
}

Register An Application

An Application is a registered integration with PFL. When you register your Application you are provided with a Client Key and Client Secret; these values allow the service to generate authorization tokens that are used to authenticate with PFLlink API. All authentication is performed using an OAuth2 bearer token which is obtained from the PFLlink Identity Server.

An Application may authenticate to the PFLlink API either as itself (Client Credentials Flow), or on behalf of a PFLlink User (Authorization code grant, or Implicit Grant). In both situations, the authentication context is associated with one or more PrintingForLess.com stores. When the Service makes API calls, it will need to specify a store (by ID) through the REST resource URL. An endpoint exists that can return the stores associated with any given OAuth Access Token.

NOTE:
Application registration via the PFLlink API is not yet available. For now, a PFLlink API Admin will need to register an Application on your behalf.

To request a new Application, send an email to apisupport@pfl.com

Authentication

The PFLlink API uses OAuth 2.0 bearer tokens to authenticate restricted API calls. The bearer token is created by the PFLlink Identity Server and contains a verifiable identity tied to either a registered Application or a PFL User. An Identity will have access to one or more resources in the PFLlink API; in simple terms, these resources are stores. A store is a collection of printed and physical fulfillment items that can be delivered to a person or business.

PFLlink Identity Server

Backing Technology

The PFLlink API uses Azure Active Directory technology for the Identity Server. Most user documentation or notes that pertain to Azure Active Directory will apply to interactions with the PFL Identity Server; this is especially helpful for understanding the various OAuth flows, the parameters expected in each step, and the responses returned by the server.

Additional Reading

• OAuth 2.0 in Azure AD

Sending the OAuth token to the PFLlink APIs

When making API calls, the access token is sent as a Bearer token through the HTTP Authorization header.

Request:

GET /API/v1/user HTTP/1.1
Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Specifying the Resource ID for the PFLlink API

When obtaining an OAuth token, the PFL Identity Server requires that the request explicitly specify that access is needed for the PFLlink API. This is done through passing a “resource” parameter in the request to the /authorize and /token endpoint with a value of https://pfl.pfllink.appportal.api.

IMPORTANT:
If the resource parameter is not included in the request to the /authorize AND /token endpoints, the OAuth token will not be able to access the PFLlink API.

Authenticating on Behalf of a PFL User

This section explains how to obtain an OAuth 2.0 Access Token using Authorization Code Grant flow.

For additional details, see https://msdn.microsoft.com/en-us/library/azure/dn645542.aspx

Use Case Notes

The Authorization Code grant flow is most appropriately used in a B2B type application where individual organizations (or sites, or accounts) of the application each have their own product store with PrintingForLess.com. The business relationship is between the individual application users and PrintingForLess.com and the application facilitates the communication between the two entities. The PFL Users are individually billed for their ordered items as configured in their individual PFL store.

The interactive flow is initiated by the Service during a hypothetical “Install” or “Configure” process; the service would acquire an Access Token and Refresh Token on behalf of a user and store them in a secure manner for later use. The tokens can then be used both during interactive operations, or for scheduled or non-interactive server-to-server type operations.

NOTE:
Remember that each Identity may be associated to one or more PFL stores. If you are creating an “Install” or “Configure” process as part of your integration, consider having the user select which store they would like to use. Alternatively, the user would select which store to use during the normal integration usage process.

Overview

1. The client application starts the flow by redirecting the user agent to the Azure AD authorization endpoint. The user authenticates and consents, if consent is required.
2. The Azure AD authorization endpoint redirects the user agent back to the client application with an authorization code. The user agent returns authorization code to the client application’s redirect URI.
3. The client application requests an access token from the Azure AD token issuance endpoint. It presents the authorization code to prove that the user has consented.
4. The Azure AD token issuance endpoint returns an access token and a refresh token. The refresh token can be used to request additional access tokens.
5. The client application uses the access token to authenticate to the Web API.
6. After authenticating the client application, the web API returns the requested data.

Authenticating as the Application (Client Credentials)

This section explains how to obtain an OAuth 2.0 Access Token for service to service calls using Client Credentials flow.

For additional details, see https://msdn.microsoft.com/en-us/library/azure/dn645543.aspx

Use Case Notes

The Client Credentials grant flow is most appropriately used in a B2C type application where application users have access to one (or few) PrintingForLess.com product stores which are owned by the developer of the application; the business relationship is between the application developer and PrintingForLess.com. The application’s users do not need to be PFL Users nor have their own stores; depending upon the implementation, they may not be aware they are interacting with PrintingForLess.com services. Instead the application developer makes her own store available to the application users and submits orders to PrintingForLess.com in a service-to-service context. The Application Developer is billed for any order items submitted by the application.

Client Credentials is a non-interactive flow appropriate for service-to-service communication. Tokens are generated using your Application’s Client ID and Client Key. While the Client ID is a quasi-public value, the Client Key should remain secure and protected. Most implementations will store these values in their application configurations and use them for all interactions with PFLlink API’s.

NOTE:
Remember that each Identity (including the Application itself) may be associated to one or more PFL stores.

Overview

1. The client application authenticates to the Azure AD token issuance endpoint and requests an access token.
2. The Azure AD token issuance endpoint issues the access token.
3. The access token is used to authenticate to the secured resource.
4. Data from the secured resource is returned to the web application.

* Request *

POST /pflportal.com/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
&client_secret=XXXXXXXXXXXXXX
&resource=https%3A%2F%2Fpfl.pfllink.appportal.api

* Result *

#!json
{
        "token_type": "Bearer",
        "expires_in": "3600",
        "scope": "user_impersonation",
        "expires_on": "1448941051",
        "not_before": "1448937151",
        "resource": "https://pfl.pfllink.appportal.api",
        "access_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}