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:

5.3.1. Introdcution

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:

  1. 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.

  2. 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.

    API self manage access token app

    or

    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.

    API no self manage access token app

  3. 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.

    API PxM calls

    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:

  1. On the API applications page, click on Orange plus icon New application button, a New OAuth2 application window opens.

    WebUI New API Application window

  2. 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.

    WebUI New API Application added

  3. Click on the API application name to be navigated to the Named detail page. The following configuration is available on this page:

    WebUI API Application named detail 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.

    Example:

    WebUI Log API expired message

    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.

    WebUI New Application API token

    Once generated the OAuth2 Client ID, secret and access token can be passed onto the 3rd party as required.