API Keys

BEEtoolkit accounts can hold up to 5 API keys at a time. Each key has an optional expiry and can be created or revoked through the web UI or through this API — making no-downtime rotation straightforward.

A typical rotation flow:

1. Create a new key with an expiry that suits your policy.
2. Update your integration to use the new key and secret.
3. Once traffic has moved across, revoke the old key.

See Authentication for details on how keys and signatures are used on every request.

---

Endpoints

Method	Path	Purpose
POST	/api/public/v1/api_keys	Create a new API key for the account.
DELETE	/api/public/v1/api_keys/{id}	Revoke an existing API key.

Authentication

Include the following headers on every request:

• Authorization: HMAC <signature>
• X-Api-Key: <your account key>
• Accept: application/json

See Authentication.

Listing keys

This API does not expose a list endpoint. Use the BEEtoolkit web UI to see the keys currently registered for an account, along with their expiry and last-used timestamps.

---

Rules

• A maximum of 5 active keys per account. Creating a 6th key returns 422 Unprocessable Entity.
• A key cannot revoke itself. Authenticate with one key, then revoke the other.
• The secret is returned only on creation. Store it immediately; it cannot be retrieved again.
• Keys without an expiry remain valid until they are explicitly revoked.

---

Attributes

Request parameters (create)

Field	Type	Required	Description
expires_in	string	no	Lifetime of the new key. Omit for a non-expiring key. See Expiry values.

Response fields (create)

Field	Type	Description
id	integer	Internal ID of the key. Used when revoking.
key	string	The public key identifier, prefixed mpk_. Sent in X-Api-Key.
secret	string	The signing secret. Returned once only.
expires_at	string | null	ISO 8601 expiry timestamp, or null if the key does not expire.
created_at	string	ISO 8601 creation timestamp.

---

Enumerations

Expiry values

• 30d
• 90d
• 180d
• 365d

Omit the expires_in parameter (or send it blank) to create a key with no expiry.

---

Create an API key

Generate a new API key and secret for the account.

POST /api/public/v1/api_keys

Request body

{
  "expires_in": "90d"
}

The body may also be empty, in which case a non-expiring key is created.

Code examples

cURL

curl -X POST "https://www.beetoolkit.co.za/api/public/v1/api_keys" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>" \
  -d '{"expires_in": "90d"}'

JavaScript (axios)

const url = "https://www.beetoolkit.co.za/api/public/v1/api_keys";
const payload = { expires_in: "90d" };

const path = new URL(url).pathname;
const signature = await generateSignature(path, payload, apiSecret, 5);

const response = await axios.post(url, payload, {
  headers: {
    Accept: "application/json",
    Authorization: `HMAC ${signature}`,
    "X-Api-Key": apiKey,
  },
});

console.log(response.data);

Response

Returns 201 Created:

{
  "id": 4231,
  "key": "mpk_Xb9aR3dv7_FQz6yp1HkTqNmLw8gV4sJcUeKoPbZxYtE",
  "secret": "kR2vN4xP9sJ6aE3yHqZ7wLbTmUgVdFcXiKoRnSpQeDt",
  "expires_at": "2026-07-15T12:34:56Z",
  "created_at": "2026-04-16T12:34:56Z"
}

Store the secret now

The secret field is the only time this value is returned. If lost, the key must be revoked and replaced.

Errors

Status	Description
422	The account already has the maximum number of keys, or expires_in is not a supported value.

Cap reached:

{ "error": "Account already has 5 API keys" }

Invalid expiry:

{ "error": "Invalid expiry duration: 999d" }

---

Revoke an API key

Delete an existing API key. Once revoked, requests authenticated with the revoked key return 401 Unauthorized.

DELETE /api/public/v1/api_keys/{id}

Path parameters

Name	Type	Required	Description
id	integer	yes	The id returned when the key was created.

Code examples

cURL

curl -X DELETE "https://www.beetoolkit.co.za/api/public/v1/api_keys/4231" \
  -H "Accept: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>"

JavaScript (axios)

const keyId = 4231;
const url = `https://www.beetoolkit.co.za/api/public/v1/api_keys/${keyId}`;

const path = new URL(url).pathname;
const signature = await generateSignature(path, "", apiSecret, 5);

const response = await axios.delete(url, {
  headers: {
    Accept: "application/json",
    Authorization: `HMAC ${signature}`,
    "X-Api-Key": apiKey,
  },
});

console.log(response.status); // 204

Response

Returns 204 No Content on success.

Errors

Status	Description
404	No key with that id exists on this account.
422	The id refers to the key used to authenticate this request. Authenticate with a different key and retry.

Self-revocation attempt:

{ "error": "Cannot revoke the key used to authenticate" }

Unknown id:

{ "error": "Key not found" }