Web API

Authentication

To get started with our API, you need to set up authentication. You can try to follow our example and make a first call – just to see how it’s like to work with our API.

If you want to access API for the first time, you need to generate your API credentials and use them to create an access token. The token is needed to authenticate API calls.

Our API uses client credentials (OAuth grant type) for obtaining a user token.

Create API keys

To create API keys, follow these steps:

  1. Log in to Piwik PRO.
  2. Go to Menu > Profile (Click on your email) .
  3. Navigate to API keys.
  4. Click Create a key.
  5. Enter Name and click OK.
  6. Copy Client ID and Client secret. The Client secret won't be available after you close this window.

Note: Credentials are valid until they are deleted in API keys.

Create an access token

To create an access token, follow these steps:

  1. Piwik PRO API tokens use JWT format.
  2. Make a call:
  curl -X POST 'https://<example>/auth/token' -H "Content-Type: application/json" --data '{
      "grant_type": "client_credentials",
      "client_id": "<client_id>",
      "client_secret": "<client_secret>"
      }'

Note: Replace with your account URL, <client_id> with your client ID, and <client_secret> with your client secret.

  1. Response example:
  {"token_type":"Bearer","expires_in":1800,"access_token":"<your_access_token>"}
  1. Now you can use <your_access_token> to communicate with Piwik PRO API. The token is a Bearer type, so you need to include it within the header in every API call.
  Authorization: Bearer <your_access_token>

Note: Every token is valid for 30 minutes. expires_in shows the expiration time in seconds.

Delete API keys

If you no longer want to use generated API credentials in access tokens, you need to delete them.

To delete API credentials, follow these steps:

  1. Log in to Piwik PRO.
  2. Go to Menu > Profile (Click on your email).
  3. Navigate to API keys.
  4. Choose credentials that you want to revoke and click X.