Document toolboxDocument toolbox

.API Permissions v2020.1

More information on the API can be found on the API page.

API Keys Grid

'API Keys' are a list of available permissions that will allow access to the data within the PCR-360 database via the API. Users can access and view the various API permissions that are being used within an organization from the Admin > API > API Keys navigation option.

API Key Grid Header example

Whenever adding or editing an API permission, the API key will be randomly generated and disabled from User modifications. Users can select the Read and Write access in various sections like 'Services', 'Equipment', 'Service Desk', and 'SNMP'. This Grid allows the User to  Add,  Edit Selected, or Delete Selected API Key Permissions.

Permissions Tab

API Keys Permissions Tab Example

A User input description is recommended whenever adding a new API Permission. This will create clarity when examining multiple API Permissions sets.

Add

Add New API Key Permission

Select the desired 'API Permission' and set any desired Expiration Date.  Depending on API Endpoint, you will see fields for granting Read and Write permissions.

Edit

Users can Edit Selected an existing API Permission if there are problems with the initial configuration.

Delete

Users can Delete Selected an existing API Permission. Care should be exercised in this action to make sure that the Permission is not being used elsewhere by PCR-360.


Users Tab

Manage API Keys Form Example

From 'API Users' Grid the User is able to Add, Edit Selected, or Delete Selected API Keys associated to a User's Session. 

Add

Add New API Key User

From the 'Add New API Users' Form, the User is prompted to Select a 'User', and Set an 'Expiration Date' for their Session.

Edit

Manage API Key User

From the 'Manage API Users' Form, only the 'Expiration Date' for the selected User's Session can be updated.

Delete

Confirm Delete Selected

When an API User is removed from the system, all other associated API Sessions will be deleted as part of the action.

User Access Validation for the API

Anonymous Mode

HTTP POST is required for the login endpoint.

A basic request looks like this:

CALLTYPE http://DOMAIN/api/API_KEY/REQUEST.OUTPUT


In this basic request example, a user of the API would replace the following:

Parameter

Replace With

CALLTYPE

We support GET and POST call types, depending on the type of request.

DOMAIN

The URL used to access your PCR-360 application

API_KEY

The unique key generated by your admin

REQUEST_TYPE

The type of request being made. Recommended type is "sql". Other available (deprecated) types are: "servicedesk", "services", and "equipment"

OUTPUT

The desired output format.

More specific requests can be done by attaching more fields at the end of the URL in a query string:

GET http://DOMAIN/api/API_KEY/REQUEST_TYPE.OUTPUT?field1=value1 ...

By sending the API_KEY in the Request, the API is able to validate if the user is able to perform the intended operation using the API.

Token Authentication

The Authentication Token is a JSON Web Token.

API Authentication Headers

This is the default behavior for the API.

When sending a Request using an Authentication Token, the following headers are Required:

PCR-AUTH-USERNAME: Caller's User Name
PCR-AUTH-PASSWORD: Caller's Password
API Authentication

A basic request looks like this:

CALLTYPE http://DOMAIN/api/KEY/login.json

This call returns an Authenticated Token that can be used in other API calls.  Depending on how User access is configured, the returned Token grants access during a configurable window. 

Once Authenticated the following header is Required for all other Requests:

PCR-AUTH-TOKEN: Caller's Authentication Token
Configuring User Session Length

The system configuration AUTH_SESSION_LIFETIME_SECONDS defines the length of time a Session is valid.  If this parameter is set to "0", then the Session is set to not expire as long as the User.  Any other value to cause the User to need to get a new Token after the defined interval, regardless of User Activity.

The system configuration AUTH_SESSION_ACTIVITY_SECONDS defined the length of time a User's Session is valid, before it times out do to Inactivity.

For more detail on these configuration values, please see the Authentication Configuration Wiki Page.

All expired tokens for the user and API key will be deleted.

API Logout

To end your Session with the API, call the Logout Endpoint.  This will end your current Session, and require you to authenticate again before you make another call using the API.

CALLTYPE http://DOMAIN/api/KEY/logout.json

Help Desk Portal - Email: help@pcr.com - Phone: 616.259.9242