Token authorisation v1.2

This guide describes a method of authenticating calls to the Permission Marketing API (PMAPI) using tokens. A token is a 96-character base64-encoded string, issued by a PMAPI server, that represents a particular user. It is similar to a session cookie, as it represents an authenticated "session" between a client and a server.

Token-authenticated requests can be issued using the PMAPI client library. We have also coded an example showing how this method can be used.

Why use Token authorisation?

Advantages of Token:

  • More fine-grained security because users do not need the company's API key. Without the API key, a user cannot make requests on behalf of other users (e.g. the account admin).
  • Delegation is a possibility: tokens could be generated by app A and then handed to app B for use, enabling app B to make API calls without knowing the user's password.
  • This method is widely understood and can make for easier testing. For example, clients like Postman are designed to work with Token authorisation.
  • Tokens expire after a set period of time, they are self-limiting.
  • Tokens are issued without disclosing the API key (Hash method), which is a vulnerable secret.

Disadvantages of Token:

  • Need to code for the "token expired" case.
  • Need to build storage for the token.

When authenticating with the Token method, all actions will be carried out on behalf of the nominated user. Please note, some functionality and content is restricted on a per user basis.

How do I authorise with a token?

PMAPI tokens are passed to the remote server in the Authorization header. A token-authenticated PMAPI HTTPS request might look like this:

Example HTTPS request headers

GET /v1/folder HTTP/1.1
Date: Tue, 30 May 2013 12:34:56 GMT
Accept: application/json
Authorization: SuTToken ERdpnHQJlZUjP81QpvxXp ...etc

Please note that all PMAPI requests must be made over SSL (HTTPS).

POST /token

Tokens are issued by a unique endpoint which creates tokens for authentication. To obtain a token, issue an unauthenticated POST request to the "token" endpoint. For this POST request, two arguments are required: username and password.

Attribute Type Description
string The 'username' of a registered user of the platform.
string The password of the registered user specified by the 'username' attribute.

If the credentials are not recognised, an error with HTTP status 401 (not authorised) will be returned. Otherwise, the PMAPI server will return a token:

Attribute Type Description
string A 96-character base64-encoded string, only valid until the 'expiry' date.
int Specifies the timestamp at which the token will expire.*

*By default, tokens are valid for 24 hours. Client code must tolerate token expiry and request new tokens as required.

There is no upper limit on the number of tokens that may be issued against a given user’s account. Any number of tokens may be active concurrently.

DELETE /token

The DELETE method can be used to delete (i.e. revoke) an access token. It supports the token filter which specifies the token to be deleted. Its behaviour depends on the type of authentication used for the request:

  • For Token authentication, the token argument is optional. If supplied, the specified token is deleted. If omitted, the token associated with the current request is deleted.
  • For all other authentication methods, the token argument is required. It specifies the token to be deleted.

Requests will error if attempting to authenticate with a revoked token.