Getting started with the CyberQP API

Introduction

With the CyberQP API, you can programmatically access the data within your CyberQP tenant. To make sure you have all the tools to use the API, this KB article details the following:

• Our URL for accessing our OpenAPI/Swagger API documentation
• What type of data you'll have access to, and how much of that data you'll be able to consume
• The process for consenting and obtaining API-related credentials
  
• Refreshing or revoking your API credentials

Preconditions

• Administrator access to CyberQP (Primary or Super role holder).
  
  

API Access to CyberQP (Scopes)

The information that's accessible via the API will be directly correlated to the data you can see in the dashboard using your CyberQP login. All API requests require the use of API credentials that are linked to the dashboard user that generated the initial access token.

At this time, a Primary or Super role holder will be able to generate API credentials to access data programmatically in CyberQP.

Because a Primary or Super role holder has access to all the data for your tenant inside of CyberQP, the API credentials generated with these roles will have access to all data for your CyberQP tenant.

List of Supported Scopes
At this time, all scopes have been enabled to retrieve data from the API.

Offline Access - Allows you to generate API credentials with a refresh token
Profile - Retrieve information about the dashboard user being used for the communication of the API
Customer - Access to the tenants' list of customers. (Customer Name, CustomerAgentID (called GUID))

NOTE: Additional functionality will be added to the API in the coming months.  Please feel free to add any additional use cases you would like to see implemented to the Feature Request Feedback portal:
https://support.getquickpass.com/hc/en-us/articles/15172083371031-Accessing-the-Feature-Request-Board   (search for API)

API Documentation (OpenAPI / Swagger Docs)

You may download the openapi (swagger) specification from:

https://us.getquickpass.com/api/docs-json

This swagger specification can be imported into Postman using their "import" option. 



You may also use our live API documentation at the following locations:

US Tenants

https://us.getquickpass.com/api/docs

(Choose this URL if you already access your tenants with https://admin.getquickpass.com/ in your browser)

EU Tenants

https://eu.getquickpass.com/api/docs

(Choose this URL if you already access your tenants with https://eu-admin.getquickpass.com/ in your browser)

You can kick off the authorization process to start using the API documentation to test making calls by clicking the "Authorize" button

You will then see a screen where you will need to click the "Authorize" button

If this is your first time using the CyberQP API, you will need to consent to using the API using your dashboard user. Click "Accept" to continue.

After accepting you'll be taken back to the Swagger site. Click the "Close" button

You'll now be ready to click any of the API endpoints

Generating your API Credentials

This section will detail how to retrieve API credentials. The US / EU Tenants URL below will return an access token, refresh token, and clientID. The refreshToken and clientID are used to get a new access token after it has expired (60 minutes).  The refreshToken is valid for 6 months or until used.  Once the refreshToken is used, a new Access Token and refreshToken are issued.

If this is your first time using the CyberQP API, you will need to consent to using the API using your dashboard user.

In your browser navigate to one of the following websites (depending on where your CyberQP tenant is hosted):

US Tenants

https://us.getquickpass.com/api/v1/auth/login

EU Tenants

https://eu.getquickpass.com/api/v1/auth/login

This URL will redirect you to our dashboard where you will need to consent to using our API. If you're not already logged in, you will be prompted to sign in and then consent to using our API. This endpoint serves as a redirector to our Dashboard to gain access to our API.



After clicking 'Accept,' you'll receive your API credentials, including an Access Token, Refresh Token, and a ClientID that represents your tenant.



Once you see these value, save them in a safe place such as a password manager as you will not be able to see them again. If you navigate to or refresh /api/v1/auth/login, you will generate a new set of API credentials.

Using your API Credentials with our Postman Collection

If you've imported our collection into Postman (using https://us.getquickpass.com/api/docs-json)

You will need to make a few minor tweaks to get the API calls to work.

1. On the "Authorization" tab, change the "Auth Type" to "Bearer Token.

2. In the "Token" section, enter your access token (retrieved from the browser using https://us.getquickpass.com/api/v1/auth/login or https://eu.getquickpass.com/api/v1/auth/login)

3. Set the base URL to either  https://us.getquickpass.com or https://eu.getquickpass.com depending on where your tenant is located.

4. You will now be able to use the CyberQP API calls in the Postman collection 

Refreshing Your Access Token

CyberQP accessTokens expire after 1 hour. Just before 1 hour, you'll need to leverage your refresh token AND client ID to gain a new access token and new refresh token.

Please use the OAuth2 "Refreshing an access token" flow to receive a new accessToken (and refreshToken)

For your convenience, a Postman collection for refreshing your access token is attached to the bottom of this KB.

Sample From Postman
1. In the "Authorization" tab, set your Auth Type to "No Auth"

2. In the Body tab, set the data transmission type to "x-www-form-urlencoded" and pass the following:
POST https://tenantregion.getquickpass.com/oauth2/token
grant_type: refresh_token (Type of token)
client_id: {your client ID} (Refer to login response)
refresh_token: {your refresh token} (Refresh token from login response)



For detailed insights into refreshing access tokens, we suggest referring to the guidelines provided at Refreshing Access Tokens (OAuth.com). These resources offer information on best practices and methodologies for maintaining secure access.

To streamline the token refresh process and enhance efficiency, we advise incorporating standard OAuth 2.0 client libraries into your scripts or application. These libraries are purpose-built to automate token refreshing, relieving developers of manual intervention and reducing the risk of token expiration issues.

A list of client libraries can be found at: https://oauth.net/code/

Revoking Your Access Token

CyberQP accessTokens can be destroyed with a revocation process. This will break any applications/scripts using this access token. Data will not be retrievable from CyberQP using the specific access token that underwent a revocation.

For your convenience, a Postman collection for refreshing your access token is attached to the bottom of this KB.

Sample From Postman

1. On the "Authorization" tab, change the "Auth Type" to "Bearer Token.

2. In the "Token" section, enter your access token
2. In the Body tab, set the data transmission type to "x-www-form-urlencoded" and pass the following:
POST https://tenantregion.getquickpass.com/oauth2/revoke
token: access (Type of token)
client_id: {your client ID} (Refer to login response)