5.3. API applications
This chapter explains how to create, manage and give access to the PxM API. The following topics are included in this chapter:
The PxM Platform REST API is a read-only API that will allow third-party applications to read data from the PxM Platform Web Management Interface.
The steps required to configure authentication and authorise the use of the PxM APIs are as follows:
Within the Web Management Interface the PxM superadmin will create a new application, see Creating and configuring a new API application. This will automatically generate a unique OAuth2 Client ID and OAuth2 Client secret. Configure the new application container with an appropriate name and notes in order to easily identify the application that will be using the access.
The next part of the configuration will depend on the application that will be accessing the PxM APIs:
If the application has the ability to self manage access tokens then it only needs the OAuth2 Client ID and OAuth2 Client secret to make the PxM oauth2/token API call.
If the third party application doesn’t have the ability to self manage access tokens then an access token will need to be added and passed onto the third party with the OAuth2 Client ID.
Once the third party application has the correct authentication, a number of PxM API calls can be made to the PxM Virtual Appliance to read the data presented in the Web Management Interface.
The following diagram shows the Web Management Interface data that can be read by the available PxM APIs.
For further information on the PxM Platform APIs see PxM Platform API documentation.
5.3.2. Creating and configuring a new API application
This page allows you to create a new API application container that will generate a unique OAuth2 Client ID and OAuth2 Client secret. The application container can then be used to manage access tokens to allow applications to make calls to the PxM API.
To add a new application:
On the API applications page, click on New application button, a New OAuth2 application window opens.
Within the New OAuth2 application window enter a unique name that will help identify the API application and be used as the display name within the Web Management Interface. Click Save. The new API application container is created and a unique OAuth2 id and secret is generated.
5.3.3. Generating an access token
If an access token is required by the application to make API calls then they can be generated on the API Application detail page.
To generate an access token:
On the API applications page, click on the API application name to be navigated to the Named detail page. The following configuration is available on this page.
Heading Description Name: The display name given to the API application to help identify it. OAuth2 Client ID Automatically generated unique ID. Can be copied by hovering over it. OAuth2 Client Secret Automatically generated unique secret. Hashed out for security but can be seen and copied by hovering over it. Notes Enter any notes you might think would be useful for future reference or for other SuperAdmins. Access tokens
Lists all the access tokens that have been created for the application.
lasted used at will display the date the access token was last used to make a PxM API call.
Expires at determines the date/time when the access token will no longer be valid. If being used by an application, the application will no longer be able to make PxM API calls.
When an access token expires, the application will be allowed to continue its on going call but the next call made will be rejected.
When an application makes an API call with an expired access token it will be logged.
New token button
Automatically generates a new access token with the selected expiration date. Hashed out for security but can be seen and copied by hovering over it.
To create a new access token, click on the New token button and select when you want the access token to expire.
Click Save. A new access token is granted and listed in the table. The access token token along with the OAuth2 Client ID can now be passed onto your 3rd party to enable them to make API calls to the PxM Platform.