The API

CoreInto has a JSON API so other programs, such as your website, a control panel or a script, can read and change records: clients, orders, services, domains, invoices, payments, tickets and more. A program signs in with an API credential made under Settings > API Credentials, calls an action at /api/v1/ACTION, and gets a JSON answer. Every call is checked against the credential's scopes, is limited to the addresses and the expiry you set, and is written to the API log. This chapter covers the credentials, how to call the API, the answers and errors, and a reference of every action.

Settings > API Credentials

The list shows each credential's description, identifier, the administrator it acts as, its access (Everything, or how many areas), allowed addresses, when and from where it was last used, and when it expires. The API Reference button opens the in-app reference page, which repeats the table at the end of this chapter with your own API address filled in.

Add Credential asks for:

When the credential is created, the page shows the identifier (32 characters) and the secret once. Copy the secret then: CoreInto keeps only its SHA-256 fingerprint and cannot show it again. If it is lost, open the credential and press Make New Secret, which gives a new secret and stops the old one. Delete removes the credential; programs using it can no longer connect.

Scopes

A scope is an area of the API. An action needs the scope shown in the reference; system.whoami needs none.

Calling the API

Address

Calls go to your site's address followed by /api/v1/ and the action:

https://www.example.com/api/v1/clients.get

Short addresses need the .htaccess rewrite that comes with CoreInto (Apache and LiteSpeed). Where addresses cannot be rewritten, name the action as a parameter instead:

https://www.example.com/api/index.php?action=clients.get

The action field may also be sent in the request body.

Signing in

Send the identifier and secret in the Authorization header:

Authorization: Bearer IDENTIFIER:SECRET

If your web server drops the Authorization header, send them as the fields identifier and secret instead (in the JSON body, the form or the query string). They are removed from the parameters before the action runs and never written to the log.

A credential is accepted when the identifier and secret match, its administrator is enabled, it has not expired, and the caller's address is in its allowed list (or the list is empty). Each successful sign-in records the time and address as "last used".

Parameters

Parameters go in one of three places, in this order of preference:

1. A JSON object in the request body, with Content-Type: application/json.
2. Form fields (application/x-www-form-urlencoded or multipart).
3. The query string. Query values sit beneath the body: a name given in both takes the body's value.

Conventions:

• Money is text with two decimals, such as "1500.00". Dates are YYYY-MM-DD.
• Yes/no values accept 1, true, yes or on for yes; anything else is no.
• Lists (such as items, lines or nameservers) are JSON arrays; in a form or query string they may be a JSON text or, for simple lists, comma-separated.
• List actions take limit (1 to 250, default 50) and offset (default 0) and return total, offset, count and the rows.
• Actions that change data must be called with POST; reading actions may use GET or POST.
• Ids are returned as numbers. Columns holding passwords, secrets, access keys and the like are never returned.

Answers

Every answer is JSON with a matching HTTP status. Success:

{"result": "success", "client": {"id": 1001, "first_name": "Sara", ...}}

Failure:

{"result": "error", "message": "There is no such client."}

Rate limiting

After 10 failed sign-ins from one address within 15 minutes, that address is refused for 15 minutes with status 429. IPv6 callers are counted by their /64 network. A successful sign-in clears the count. There is no limit on successful calls.

The API log

Every call, successful or not, is written to Utilities > API Log with the credential, action, address, HTTP status, time taken, the parameters and the answer. Parameters whose names contain pass, secret, token, epp or auth are stored as "(hidden)". The log can be filtered by date, action, address and failed calls only, and old entries can be removed under System Cleanup. The setting "Log every API call" on the Security tab of General Settings has no effect in this version: calls are always logged.

Examples

Who am I, with GET:

curl https://www.example.com/api/v1/system.whoami \
  -H "Authorization: Bearer 3f9c2b7e1a4d4c6f8e0b2a1d9c7e5f31:kq8Zr2vN0tXy5WbLm3Hc7dPa9Rs1Ue4Fg6"

A client by email address, with JSON parameters:

curl -X POST https://www.example.com/api/v1/clients.get \
  -H "Authorization: Bearer IDENTIFIER:SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email": "sara@example.com"}'

Place an order for one product and one domain, and email the confirmation:

curl -X POST https://www.example.com/api/v1/orders.add \
  -H "Authorization: Bearer IDENTIFIER:SECRET" \
  -H "Content-Type: application/json" \
  -d '{"client_id": 1001, "email": true,
       "items": [
         {"type": "product", "product_id": 3, "term": "annually", "domain": "example.com"},
         {"type": "domain", "name": "example.com", "action": "register", "years": 1}
       ]}'

Record a bank transfer against an invoice, as form fields:

curl -X POST https://www.example.com/api/v1/invoices.add_payment \
  -H "Authorization: Bearer IDENTIFIER:SECRET" \
  -d invoice_id=5012 -d amount=49.00 -d gateway=banktransfer -d transaction_id=TRF-20261009-17

Where addresses cannot be rewritten, and the Authorization header is dropped by the server:

curl "https://www.example.com/api/index.php?action=tickets.list&open_only=1" \
  -d identifier=IDENTIFIER -d secret=SECRET

Reference

Parameters marked with * are required. "Changes data" means the action must be called with POST.

System

Clients

Catalogue

Orders

Items for orders.add are objects in a list. A product:

{"type": "product", "product_id": 1, "term": "monthly", "qty": 1, "domain": "example.com",
 "options": {"4": 2}, "addons": [3], "ns1": "", "ns2": ""}

options maps a configurable option id to the chosen value id (or quantity); addons lists add-on ids. A domain:

{"type": "domain", "name": "example.com", "action": "register", "years": 1, "epp": "", "nameservers": []}

action is register or transfer; epp is the transfer code.

Services

Licences

These belong to the Licensing Manager add-on; see Licensing Manager.

Domains

Billing

Support