Authorized API guide¶

Introduction¶

This page describes how to access Piwik PRO API which uses client credentials OAuth grant type for obtaining user token. All data is sent and received as JSON and is compliant with JSON API specification.

Obtaining token¶

If you want to access API for the first time you need to generate your API credentials which then allows you to request for a token that is used for authentication during communication with authorized API.

Generate API Credentials¶

Login to your account using your email and password.
Go to your profile (Menu then User panel).
On this page click on API Credentials tab. This page allows you to manage all your API credentials.
Click Generate new credentials which will result in new popup. Fill in your custom credentials name. Name must contains at least 3 characters.
Copy your newly generated CLIENT ID and CLIENT SECRET because they won’t be available for you after dismissing this window.

Those credentials will be valid as long as you will not revoke them in your profile.

Create access token¶

Having generated your API Credentials, now you are ready for creating access token that will be used in communication with API.

Piwik PRO API tokens use JWT format.

Make POST call to https://<domain>/auth/token with header Content-Type: application/json and payload: { "grant_type": "client_credentials", "client_id": "<client_id>", "client_secret": "<client_secret>" }.

Response example:

{"token_type":"Bearer","expires_in":1800,"access_token":"<your_access_token>"}

Now, you can use obtained <your_access_token> for communication with Piwik PRO API. Field expires_in stands for time (in seconds) for token expiration (TTL). Since token is a Bearer type, it must be included in every API call within header.

Authorization: Bearer <your_access_token>

Deleting API Credentials¶

Once you want to revoke the possibility of generating API token using given CLIENT ID and CLIENT SECRET, go to User panel and click Delete button on selected API credentials.

API usage example¶

Whatever API call you choose, first remember that you must generate API credentials for obtaining client id and secret.

API usage example with curl¶

For sake of this examples, https://<domain> is a URL of your PPAS instance (e.g. https://example.piwik.pro) and our goal is to perform basic operations on an app. We will:

create an app
get created app
update its attributes
remove the app

Generate your access token¶

Request example:

POST /auth/token

curl -X POST 'https://<domain>/auth/token' -H "Content-Type: application/json" --data '{
    "grant_type": "client_credentials",
    "client_id": "your_generated_client_id",
    "client_secret": "your_generated_client_secret"
}'

Response example:

{
    "token_type":"Bearer",
    "expires_in":1800,
    "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJwcG1zIiwiYXVkIjoiaHR0cHM6XC9cL3Rlc3RpbmcucGl3aWsucHJvXC9zZXR5LCJzdWIiOiJkNmNkZGMxMS1iZDA1L0aW5ncyIsImlhdCI6MTUzNzI3MDQ1OSwiZXhwIjoxNTM3MzU2ODUTRhYmUtYWIyZC02YjlhNjIxZmU0ZDciLCJvcmciOiJkZWZhdWx0In0.Nec2mYFRv6manzXjq0sHQxINZvu-fbDYT8AedVHBKYvu1F9hYKaFReY8rNgfsMANw2OX8-IKpTrQb1DyRkG4nxpIEbob528_lPd7roho5mtKlE8sfS9WZE1piYOwaNDySDEUwUowgj2xBiJqSODjxBI6qVhLkynGEEeNBVh-lrUmlcjpYqUc3saHvX72L-rqbIHa_1dzGarR-dcPyns-RpKjZEILzUSYOHdM09KDti-xsG-nbKHGdP8fVEEJPyupnAfJPOLHQg_j1c5IvJSvTKVF3j4_zo6Zw5g8YkaheT9Iwph5BGHFRneXatcmbwKI8JzSDFi6CinzI-okYKRPbg"
}

Field access_token contains your token which then will be used for all API calls. Once you generated an access token, you can use it during its lifetime (30 minutes by default)

Create an app¶

Request example:

POST /api/apps/v2

curl -X POST 'https://<domain>/api/apps/v2' -H "Authorization: Bearer <your_access_token>" -H "Content-Type: application/vnd.api+json" --data '{
  "data": {
    "attributes": {
      "timezone": "UTC",
      "name": "AppName",
      "urls": [
        "http://example.com"
      ],
      "currency": "USD"
    },
    "type": "ppms/app"
  }
}'

Note, that you have to replace:

<domain> with your PPAS instance URL,
<your_access_token> with your generated access token

Response example:

{
   "data":{
      "type":"ppms/app",
      "id":"b30e538d-4b05-4a75-ae25-7eb565901f38",
      "attributes":{
         "name":"AppName",
         "addedAt":"2018-09-13T12:16:30+00:00",
         "urls":[
            "http://example.com"
         ],
         "timezone":"UTC",
         "currency":"USD",
         "excludeUnknownUrls":false,
         "keepUrlFragment":true,
         "eCommerceTracking":false,
         "siteSearchTracking":true,
         "siteSearchQueryParams":[
            "q",
            "query",
            "s",
            "search",
            "searchword",
            "keyword"
         ],
         "siteSearchCategoryParams":[

         ],
         "delay":500,
         "excludedIps":[

         ],
         "excludedUrlParams":[

         ],
         "excludedUserAgents":[

         ],
         "gdpr":true,
         "gdprUserModeEnabled":false,
         "privacyCookieDomainsEnabled":false,
         "privacyCookieExpirationPeriod":31536000,
         "privacyCookieDomains":[

         ],
         "organization":"default",
         "appType":"web",
         "gdprLocationRecognition":false
      }
   }
}

Get an app¶

Now, when app is added, it is possible to get it.

Request example:

GET /api/apps/v2/<app_id>

curl 'https://<domain>/api/apps/v2/b30e538d-4b05-4a75-ae25-7eb565901f38' -H "Authorization: Bearer <your_access_token>" -H "Content-Type: application/vnd.api+json"

Notice: URL contains b30e538d-4b05-4a75-ae25-7eb565901f38. What is it? It is unique ID of an app. If you want to update given resource you must specify which one. How to obtain this ID? You can obtain ID from response’s ‘data/id’ field when you added an app

Response example:

{
   "data":{
      "type":"ppms/app",
      "id":"b30e538d-4b05-4a75-ae25-7eb565901f38",
      "attributes":{
         "name":"AppName",
         "addedAt":"2018-09-13T12:16:30+00:00",
         "urls":[
            "http://example.com"
         ],
         "timezone":"UTC",
         "currency":"USD",
         "excludeUnknownUrls":false,
         "keepUrlFragment":true,
         "eCommerceTracking":false,
         "siteSearchTracking":true,
         "siteSearchQueryParams":[
            "q",
            "query",
            "s",
            "search",
            "searchword",
            "keyword"
         ],
         "siteSearchCategoryParams":[

         ],
         "delay":500,
         "excludedIps":[

         ],
         "excludedUrlParams":[

         ],
         "excludedUserAgents":[

         ],
         "gdpr":true,
         "gdprUserModeEnabled":false,
         "privacyCookieDomainsEnabled":false,
         "privacyCookieExpirationPeriod":31536000,
         "privacyCookieDomains":[

         ],
         "organization":"default",
         "appType":"web",
         "gdprLocationRecognition":false
      }
   }
}

Update app¶

Consider you added app, but afterwards you want to change its name.

Request example:

PATCH /api/apps/v2/<app_id>

curl -X PATCH 'https://<domain>/api/apps/v2/b30e538d-4b05-4a75-ae25-7eb565901f38' -H "Authorization: Bearer <your_access_token>" -H "Content-Type: application/vnd.api+json" -v --data '{
  "data": {
    "attributes": {
      "name": "NewAppName"
    },
    "type": "ppms/app",
    "id": "b30e538d-4b05-4a75-ae25-7eb565901f38"
  }
}'

This request changed app name from AppName to NewAppName.

Notice three things:

-X PATCH before URL. It means that this request is available using HTTP PATCH method

you have to specify also data/id - it’s a JSON API requirement

also data/type is required. For example, when you want to work with app resource, specify it’s type as ppms/app

you can set only parameters you want to update. For more apps attributes go to App edit reference

API will return 204 No Content status code with an empty response.

Delete an app¶

Sometimes resources are not needed anymore, so let’s have a look at example on how to delete them.

Request example:

DELETE /api/apps/v2/<app_id>

curl -X DELETE 'https://<domain>/api/apps/v2/b30e538d-4b05-4a75-ae25-7eb565901f38' -H "Authorization: Bearer <your_access_token>" -H "Content-Type: application/vnd.api+json"

There is no response example. API will return 204 No Content status code.

API usage example with Postman¶

Postman is a multiplatform GUI application for creating API calls. PPAS allows you to export swagger documentation and easily import it to Postman. Depending of what you want to work with, you can import given swagger docs:

Simply click in Postman: import -> Import From Link. Then all of your paths are imported! You have to override two things:

replace your domain in url
add token. Click on Authorization tab on chosen API call and then use Bearer Token type. Paste your token and now you can call API using SEND button.

FAQ¶

Here you can find the most common issues encountered during work with the API

API returns `"application/json" is not a valid JSON API Content-Type header, use "application/vnd.api+json" instead"`¶

Remember, all API calls needs to be created with Content-Type: application/vnd.api+json header. If you use curl you need to use -H "Content-Type: application/vnd.api+json" flag. Postman allows configuring headers with Header tab.

API returns `JWT not found`¶

Remember, you need to always use your API token. You need to send it all the time within Authorization: Bearer <your_access_token> header. If you use curl you need to use -H "Authorization: Bearer <your_access_token>" flag. Postman allows configuring tokens in authorization tab. Choose type Bearer Token and paste it there. Remember to keep this token secure as it allows access to sensitive data!

API returns `Expired JWT Token`¶

Every token that you generated is specified by TTL - time to live. By default it’s 30 minutes. After token is expired, you need to generate your access token

API returns `access token not authorized`¶

This message means, that you sent access token within proper Authorization: Bearer field, although it is invalid. Make sure you set proper token.

Authorized API guide¶

Introduction¶

Obtaining token¶

Generate API Credentials¶

Create access token¶

Deleting API Credentials¶

API usage example¶

API usage example with curl¶

Generate your access token¶

Create an app¶

Get an app¶

Update app¶

Delete an app¶

API usage example with Postman¶

FAQ¶

API returns "application/json" is not a valid JSON API Content-Type header, use "application/vnd.api+json" instead"¶

API returns JWT not found¶

API returns Expired JWT Token¶

API returns access token not authorized¶

API returns `"application/json" is not a valid JSON API Content-Type header, use "application/vnd.api+json" instead"`¶

API returns `JWT not found`¶

API returns `Expired JWT Token`¶

API returns `access token not authorized`¶