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.
Admin calls
Section titled “Admin calls”update
Section titled “update”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)
update_ips
Section titled “update_ips”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)
ip_changes_clear
Section titled “ip_changes_clear”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.
ip_request_approve
Section titled “ip_request_approve”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).
ip_request_refuse
Section titled “ip_request_refuse”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.
Client calls
Section titled “Client calls”reset (client)
Section titled “reset (client)”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.
update_ips (client)
Section titled “update_ips (client)”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.
ip_add (client)
Section titled “ip_add (client)”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.
ip_remove (client)
Section titled “ip_remove (client)”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.
ip_request_withdraw (client)
Section titled “ip_request_withdraw (client)”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.
Guest calls
Section titled “Guest calls”check (guest)
Section titled “check (guest)”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
