Getting Started

Need assistance? Contact support@qwarecmms OR call 1-888-697-2811

Accessing Q Ware data has never been easier! Easily build apps to expand Q Ware's capabilities and connect with other applications you already use. A few administrative tasks need to be done before getting started:

  1. Be sure you have the necessary permissions to access the API. This is required to be able to login to the portal and send requests to the API. This can be managed by going to your user record within the main Q Ware application and checking "Enable API Access" and saving. You must have the user group privilege "Manage API Access" to do this.

  2. If your tenant is utilizing single sign-on instead of the standard basic authentication (username and password), you must assign a password to your user account. This can be done by going to your user record and entering a value for "New Password" and "Confirm Password" under the Security and Access Section. You will use your username (email) and password to acquire access tokens.

  3. Be sure to have your tenant key and tenant id available as it is required to login to the portal, send requests to the API, and are often required parameters for requests. This information can be found in the Developer Section of application settings in the main Q Ware Application. Users must also have the privilege to view application settings.

  4. Login to the portal using your tenant key, username, and password to automatically create a new portal account.

  5. You must subscribe to the API by going to the Products area of the portal, and subscribing to one of the products to receive Subscription Keys to use for your requests. Subscription keys are issued on a per user basis and allow the API to track metrics for requests made using the keys as well as applying certain policies such as rate limiting. Requests must contain an HTTP header for "Ocp-Apim-Subscription-Key" with one of the keys as the value.

  6. You can use the portals built-in Testing Console to send requests or you can use other API testing applications such as Postman. The portal will store access tokens for you for the life of the token so they can be reused for subsequent requests through the portal. Applications like Postman will offer better token management ability.

Authentication

The Q Ware API acts as it's own authorization server, meaning it manages it's own token issuance and permissions. All requests to the API must contain an Authorization header with a valid bearer token as well as a header for "Ocp-Apim-Subscription-Key" with a valid subscription key.

Authorization: bearer {{access_token}}
Ocp-Apim-Subscription-Key: {{subscription_key}}

To see examples of requesting a token, reference the /Token endpoint in the API documentation.

Rate Limiting

The Q Ware API enforces two limiting policies to make sure it stays performant and is made available for users fairly. Requests are limited on a per user basis and a quota is tracked on a per IP address basis.

Limits

User Limit - 20 requests/minute

IP Quota Limit - 250 requests/hour

User Limit Error (429)

When the user limit is exceeded, requests will result in a 429 (Too Many Requests) error. This error response will have a "Retry-After" header that can be referenced to know when the limit will be reset.

Retry-After: {{seconds_until_limit_resets}}

IP Quota Limit Error (403)

When a single IP address exceeds the quota limit, requests will result in a 403 (Forbidden) error.

Response Caching

All GET request responses are cached for 5 minutes from the time an initial request is sent. Requests made after the caching period has expired, will execute an actual request to the API and reset the caching period. Cached responses DO NOT count toward the rate limiting policy.