Documentation

API Authentication

Authentication Overview

The QReserve API should be accessed through the use of bot users in your site. Each bot user can have an API key associated with it to perform authenticated HTTPS requests to the API. An API key is shown to you only once at the time it is generated and should then be stored securely as though it were any other password.

Generating an API Key

Create a Bot User

Administrator access is required.

Create a new bot user and give it an appropriate name. By default all bot and test users are given the role User but then can be modified after they are created.

create-bot-user.png

Upgrade Bot User Role

It is often the case that a bot user has more utility when it has the role of Administrator or Moderator in your site. Upgrade its role as you would other users and note that, once upgraded, this user can only perform actions via the API and cannot be used as a regular test user.

upgrade-bot-user-role.png

Generate an API key

Select your new bot user and then visit the API Key tab. Click the Generate a new API key button to generate your API key.

IMPORTANT: The full API key will only be shown to you this once. Copy it and store it in a safe location as though it were any other password. Only the first 8 characters are shown in subsequent views of this page.


new-api-key.png

Restrict IP Addresses

If you know that you will be accessing the QReserve API from a single IP address or a list or range of IPs you can restrict this API key to those IPs. Any requests from other IP addresses will fail as though the API key were invalid. Multiple IP addresses or ranges (in CIDR format) can be provided separated by commas. Leave blank to allow this API key to be used without any IP address restrictions.

Example IP Restrictions

1.2.3.4
1.2.3.0/24
1.2.3.4,99.100.101.102
1.2.3.0/24,99.100.101.0/24

API Key Maintenance

Regenerating an API Key

If at any time you wish to regenerate an API key you may do so; however, this will overwrite the previous API key and make it unusable for all future requests.

Clear an API Key

If at any time you wish to clear an API key you may do so. Removing a bot user from your site will also have the effect of clearing the API key from that user.

Using an API Key

All HTTPS requests to the API must be autheticated by passing your API key in the Authorization HTTP header. The API key used in the examples below is not a valid key and should be replaced with your own.

Examples

curl

1curl -H "Authorization: QR-1grc2qc9firo5lwkxn9yrynzbqxdtsda01tlve" https://api.qreserve.com/users/self

Python

1import requests
2

3url = 'https://api.qreserve.com/users/self'
4api_key = 'QR-1grc2qc9firo5lwkxn9yrynzbqxdtsda01tlve'
5

6r = requests.get(url, headers={'Authorization': api_key})
7if r.status_code == 200:
8  r_json = r.json()

Node

1var request = require('request');
2var apiKey = 'QR-1grc2qc9firo5lwkxn9yrynzbqxdtsda01tlve';
3var options = {
4  url: 'https://api.qreserve.com/',
5  headers: {
6    'content-type': 'application/json',
7    'Authorization': apiKey
8  },
9};
10

11request(options, (error, response, body) => {
12  console.log(response.statusCode);
13  console.log(body);
14});