Microkeeper API

The Microkeeper API lets your software read and write a Microkeeper account's data, such as staff, rosters, timesheets, leave and pay runs. Every request goes to one address, with two keys: a developer key that identifies your software, and a business key that identifies the account and what you may do in it.

This guide covers how to:

1. Make your API keys.
2. Send a request.
3. Read the response and errors.
4. Check the access each action needs.
5. Log your requests while you build.

Make your API keys

Register a Microkeeper account for your software, if you don't have one. In Menu > Settings > General > Global, under Business Contact, fill in the Business Name: customers see it when your software reaches their account, and requests are refused while it's blank.

Your developer key: mk_dev_key

1. Navigate to Menu > Settings > General > Global, then Developers.
2. Beside Developer Key, click Manage Developer API Keys. It opens in a new tab.
3. Click Create New API Key, enter the Name of Application, and click Generate API Key.
4. Click Copy to Clipboard, and store the key on your server.

Your developer key is the same for every account you connect to. Keep it on your server: never put it in a browser, an app or code you share.

A business key for each account: mk_biz_key

Each account you connect to makes a business key for you, with the access your software needs. On that account:

1. Navigate to Menu > Settings > General > Global, then Developers.
2. Beside API Business Keys, click Manage Business API Keys.
3. Click Create New API Key, and enter the API use case, such as your software's name.
4. Under Access Permissions, choose No Access, Read Only or Read/Write for Roster, Payroll, HR/Staff and Account. Every module starts at No Access.
5. Click Generate API Key, and copy the key.

Each key is shown once, when it's made. If one is lost, revoke it and make a new one. A business key's access can be changed later with Edit, and Revoke Key stops it working straight away.

Send a request to the Microkeeper API

Send every request as an HTTPS POST to:

https://microkeeper.com.au/api_post.php

with these four form fields:

Send them form-encoded (application/x-www-form-urlencoded), with each value URL-encoded. The keys go in the form fields, not in headers.

Example in PHP

$post_data = [
    'mk_dev_key' => getenv('MK_DEV_KEY'),
    'mk_biz_key' => $account['mk_biz_key'],
    'mk_action'  => 'hello_world',
    'mk_data'    => json_encode(['hello' => 'world']),
];

$curl = curl_init('https://microkeeper.com.au/api_post.php');
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($post_data));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_TIMEOUT, 60);
$response = json_decode(curl_exec($curl), true);
curl_close($curl);

if ($response['success'] !== '1') {
    // $response['message'] says why
}

Example with curl

curl https://microkeeper.com.au/api_post.php \
  --data-urlencode "mk_dev_key=$MK_DEV_KEY" \
  --data-urlencode "mk_biz_key=$MK_BIZ_KEY" \
  --data-urlencode "mk_action=hello_world" \
  --data-urlencode 'mk_data={"hello":"world"}'

Test your connection with hello_world

Send hello_world with any JSON in mk_data. A working connection answers with the account it reached:

{"success":"1","authenticated":"1","message":"Hello World! Accessed: southerncross"}

hello_world needs no access level, so it shows your keys work before you set up access.

Read the response

Every response is JSON with:

• success: "1" if the action worked, "0" if not. It's a string.
• authenticated: "1" if both keys were accepted, "0" if not.
• message: what happened, or why it failed.
• data: the action's results, when it has any. Each action's guide shows its data.

Check success, not only the HTTP status: an action that can't be done answers HTTP 200 with "success":"0" and a message, such as "There is no timesheet data for this period".

Errors from the Microkeeper API

Problems with the request or keys answer with an HTTP error and "authenticated":"0":

Once the keys are accepted, other problems answer HTTP 200 with "success":"0":

• mk_data is not correctly formatted JSON: mk_data isn't valid JSON.
• Action unknown: get_everything: the action name is wrong.
• Global Settings not complete yet. Settings > General > Global to correct: the account hasn't finished its Global Settings, so nothing can run yet.
• Each action's own messages, listed in its guide.

The access each action needs

A business key needs Read Only or Read/Write on the action's module. Read/Write includes Read Only.

Locations, Roles and Jobs are under Account, as they're part of the account's set-up. hello_world and create_account need no access level.

Log your requests while you build

On the account you're testing against, navigate to Menu > Settings > General > Global > Developers, and set API Logging to API Logging On - Accounts. Every request that reaches the account is then logged.

Open the log from API Logs on the Business or Developer API Keys page. It shows the last 1,000 requests from the past 30 days: each one's action, whether it worked, the first 1,000 characters of the request, and the message for those that failed. Type in Search API Logs to find a request. Turn logging off when you're done.

The Microkeeper API's actions