Pugpig Security API Explanation

The Pugpig Security API consists of three mandatory methods (Sign In, Verify Subscription and Edition Credentials), and two optional one (Renew Token, Sign Out).

For the formal specification of these methods, see Security API Specification

Sign In

This is called by the app when a user first logs in. In most cases, a user will only log into the app once (unless they explicitly log out or you are supporting the expiration of tokens). The inputs to this call are the credentials a user needs to authenticate (for example Subscription ID + Surname or Username  + Password). On success, the response will return a user token. On failure, the response should include an appropriate error message.

This call is intended to validate that a user is recognised by your subscription system, and it should return the same information regardless of whether the user's subscription is active or lapsed.

This call can optionally return a second token - this will be sent to the content server on requests for the top level OPDS feeds in the Authorization header. It should only be used if the OPDS feed will vary based on this header, and the server also needs to send a Vary: Authorization response header.

The client application will store this token for future API calls. The client should not store any of the credentials entered into the login form in the app.

As this call often passes sensitive information, we recommend it is always done over HTTPS, and using HTTP POST (if you use GET they are often recording in server logs).

Verify Subscription

This call is made whenever a logged in user opens the application. It tells the client which issues the user has access to, and also provides any messaging that might be useful to show the user. This controls which editions in the app will have a “Download” button instead of a “Buy” button. It could also say something like “You are currently a Gold Subscriber. Your subscription will expire in 2 months”.

The only input to this call is the user token generated on sign in. If this token is invalid, this call with return an appropriate error, and either trigger a renew token or sign out.

Edition Credentials

This method is used to retrieve an edition credential token from the server. This is the token that will allow them access to a particular edition. These edition credential tokens are stored on the client indefinitely once retrieved, unless the app has decided to explicitly delete them. As a result, default behaviour is that once a user has downloaded an edition, they’ll continue to have access to it even once their subscription has expired.

The API supports a standard username:password credentials combination which is sent as an HTTP Authorization header. However, the response can instruct the app to send any other arbitrary headers for content reqests to the edition.

This method is called once per edition for each logged in user, when the edition is downloaded (either explicitly by the user or as a result of a background/Newsstand download).

The only input to this call is the user token generated on sign in. If this token is invalid, this call with return an appropriate error, and either trigger a renew token or sign out.

Renew Token

This method is the same as Sign In, except that the credentials passed in is the old, invalid token as opposed to user entered details. It will be called by the client if it discovers (via a call to Verify Subscription or Edition Credentials) that a token has expired or is invalid.

This method is optional. If the server does not support this, the client will simply log the user out (i.e. delete the user token) if it sees that a token is invalid. The user will then be prompted to re-enter this credentials into the login form. Note that is you are expiring tokens, then something like a background/Newsstand download might fail if the token has expired as the user will not be able to re-enter their credentials.

Sign Out

This method takes only the token, and is called when a user logs out of the app. We do not recommend it to be used, but it can help when trying to implement server side limitations of concurrent logs. This is NOT guaranteed to be called. For example, a user may sign out while offline, or simply uninstall the app.

Subscription System Flow Charts

User opens application and User Signs In

The flow below occurs when a user signs in, or when a user opens the app. The app open flow also occurs when a background download initiates an app open. A future release plans to remove the call to Verify Subscription when opened in the background.


User downloads edition

The flow below outlines what occurs when an edition is downloaded. This could be due to a user clicking the download button, or a push initiated background download

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Powered by Zendesk