Skip to content

API Key Product API

An API key product sells a key that your own software checks with the guest check call. A key may be limited to IP addresses or ranges, or to a number of servers with client self-service (see Client IP limits). See API key product. Calls find the key by its order (order_id) or by the key itself (key).

Admin calls need Module access on the Serviceapikey card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.

POST /api/admin/serviceapikey/update

Replaces the settings (config) of an API key service. The key itself is changed only by reset.

Permission: Manage API keys (serviceapikey.manage)

Parameter Type Description
order_id integer, required The order of the API key.
config object The new settings. They replace the old ones, so send them all. The IP limit state is kept.
api_key string If sent, it must be the current key.

Returns: true.

Errors:

  • You must provide the API key order ID in order to update it. (code 9999)
  • Order not found (code 9999)
  • API key does not exist (code 9999)
  • To change the API key, please use the reset function rather than updating it. (code 9999)

POST /api/admin/serviceapikey/reset

Makes a new key for an active API key service (for a key that leaked). The old key stops working.

Permission: Manage API keys (serviceapikey.manage)

Parameter Type Description
order_id integer The order of the API key. Send order_id or key.
key string The current key.

Returns: true.

Errors:

  • You must provide either the API key or API key order ID in order to reset it. (code 9999)
  • Order not found (code 9999)
  • API key does not exist (code 9999)
  • Order is not active (code 9999)

POST /api/admin/serviceapikey/update_ips

Sets the IP addresses or ranges a key may be checked from. Staff are not held to the server limit or the 20-entry limit of a plan with a server limit.

Permission: Manage API keys (serviceapikey.manage)

Parameter Type Description
order_id integer The order of the API key. Send order_id or key.
key string The current key.
allowed_ips mixed IP addresses or CIDR ranges, as a list or as text split by spaces, commas or new lines. At most 20 without a server limit; with one, single addresses only. Empty: any address.

Returns: true.

Errors:

  • This is not an IP address or range: 203.0.113 (code 9999)
  • You can add at most 20 IP addresses or ranges. (code 9999)
  • With a server limit, the list holds single IP addresses, not ranges: 203.0.113.0/24 (code 9999)

POST /api/admin/serviceapikey/ip_changes_clear

Forgets which of the key’s IP addresses checks have used, so the client can again remove them as free typo fixes.

Permission: Manage API keys (serviceapikey.manage)

Parameter Type Description
order_id integer The order of the API key. Send order_id or key.
key string The current key.

Returns: true.

Written to the order’s history.

POST /api/admin/serviceapikey/ip_request_approve

Approves the client’s waiting IP change request and applies it.

Permission: Manage API keys (serviceapikey.manage)

Parameter Type Description
order_id integer The order of the API key. Send order_id or key.
key string The current key.

Returns: true.

Errors:

  • There is no IP address request waiting. (code 9999)
  • The change no longer fits, so it was refused and the client was told: … (code 9999) when the change can no longer be applied

The client is told (history, notification and email).

POST /api/admin/serviceapikey/ip_request_refuse

Refuses the client’s waiting IP change request.

Permission: Manage API keys (serviceapikey.manage)

Parameter Type Description
order_id integer The order of the API key. Send order_id or key.
key string The current key.
reason string Why, shown to the client.

Returns: true.

Errors:

  • There is no IP address request waiting. (code 9999)

The client is told.

POST /api/client/serviceapikey/reset

Makes a new key for one of the client’s active API key services. The old key stops working.

Parameter Type Description
order_id integer The order of the API key. Send order_id or key.
key string The current key.

Returns: true.

Errors:

  • API key does not exist (code 9999) for a key of another client
  • Order is not active (code 9999)

Authorized users need the Manage services permission.

POST /api/client/serviceapikey/update_ips

Sets the IP addresses or ranges the client’s key may be checked from (plans without a server limit).

Parameter Type Description
order_id integer The order of the API key. Send order_id or key.
key string The current key.
allowed_ips mixed Up to 20 IP addresses or CIDR ranges, as a list or text split by spaces, commas or new lines. Empty: any address.

Returns: true.

Errors:

  • This plan has a server limit: add or remove one IP address at a time. (code 9999)
  • This is not an IP address or range: 203.0.113 (code 9999)
  • You can add at most 20 IP addresses or ranges. (code 9999)

Authorized users need the Manage services permission.

POST /api/client/serviceapikey/ip_add

Adds a server’s IP address to a key whose plan has a server limit. With staff approval on, it waits as a request.

Parameter Type Description
order_id integer The order of the API key. Send order_id or key.
key string The current key.
ip string, required One IP address.

Returns: true.

Errors:

  • This IP address is already on the list. (code 9999)
  • This is not a single IP address: … (code 9999)
  • This plan has no server limit, so its IP addresses are not added or removed one at a time. (code 9999)
  • A change of these IP addresses is already waiting for approval. (code 9999)
  • Only our staff can change these IP addresses. Please open a ticket. (code 9999)

Adding into a free place is free. Authorized users need the Manage services permission.

POST /api/client/serviceapikey/ip_remove

Removes an IP address from a key whose plan has a server limit. It counts as one of the IP changes of the last 30 days, unless it was added in the last 24 hours and never used.

Parameter Type Description
order_id integer The order of the API key. Send order_id or key.
key string The current key.
ip string, required The IP address to remove.

Returns: true.

Errors:

  • You have used your 2 IP changes for 30 days. The next one is free on … (code 9999)
  • A change of these IP addresses is already waiting for approval. (code 9999)
  • Only our staff can change these IP addresses. Please open a ticket. (code 9999)

Authorized users need the Manage services permission.

POST /api/client/serviceapikey/ip_request_withdraw

Withdraws the client’s IP change request that waits for staff approval.

Parameter Type Description
order_id integer The order of the API key. Send order_id or key.
key string The current key.

Returns: true.

Errors:

  • There is no IP address request waiting. (code 9999)

Authorized users need the Manage services permission.

POST /api/guest/serviceapikey/check

Checks whether an API key is valid for the calling server: the service is active and not expired, and the caller’s IP address is allowed. Call it from the software that uses the key.

Parameter Type Description
key string, required The API key.

Returns: true when the key may be used from this IP address, else false. A valid check counts towards the key’s use count and last-used time; with “Bind on first check”, it can take a free server place for the caller’s IP.

Errors:

  • You must provide an API key to check it’s validity. (code 9999)
  • API key does not exist (code 9999)
  • Rate limit exceeded. Please try again later. (code 429)
Example

Request parameters:

{
"key": "EXAMPLE-KEY-1234"
}

result:

true