Getting started

From scratch to your first request.

1. Get an application key

Ask the website administrator for a key for your application (coolcms_ and 64 characters). They create the application in Settings → Applications with Api access and hand the key over to you. It is sent in the X-API-Key header on every request, over HTTPS only. Without it the API returns 401. The full key is shown only once, so store it. See Authentication.

export API_KEY="coolcms_0123…"   # paste your key

With the key alone you see what an anonymous website visitor sees:

curl "https://your-site.com/api/blog/article/get-all?limit=5" -H "X-API-Key: $API_KEY"

2. Sign in

Signing in is needed only when the application acts on behalf of a user. The key is sent here too.

curl -X POST https://your-site.com/api/system/auth/login \
  -H "X-API-Key: $API_KEY" \
  -d "username=your-account" \
  -d "password=your-password"

The body must be form-encoded, not JSON

The authentication endpoints read application/x-www-form-urlencoded. A JSON body is not read and the sign-in fails.

Response:

{
  "success": true,
  "message": null,
  "data": {
    "user": { },
    "token": "<access token>",
    "refreshToken": "<refresh token>",
    "payload": { }
  },
  "code": 0
}

3. Make your first read

curl "https://your-site.com/api/blog/article/get-all?limit=5&computeTotalCount=1" \
  -H "X-API-Key: $API_KEY" \
  -H "Authorization: Bearer <access token>"

Without computeTotalCount=1 the totalCount is zero

That is not an empty result; it simply was not computed.

4. Unwrap the response

The data is not in items. items holds only references; the actual values are in _references. See Response format.

5. Refresh the token

An access token lasts 15 minutes. Then:

curl -X POST https://your-site.com/api/system/auth/refresh \
  -H "X-API-Key: $API_KEY" \
  -d "refreshToken=<refresh token>"

It returns a new pair — the old refresh token stops working.

Store the new refresh token, or you will be signed out

Using the old one after a refresh is treated as theft and invalidates the whole chain.

Checklist before going live

• Every request carries X-API-Key and the key is kept secret on the server (Authentication).
• Parameters go in the URL, not the body — except passwords, which go only in the body (Authentication).
• Your parser handles two response shapes.
• You check success, not just the HTTP status.
• You check Content-Type — 404 and 500 return HTML.
• You can handle a 401 at any time, not only after expiry — and tell code 501 (key) from 103 (token).
• Your domain is on the allowed origins list.
• On a 429 you wait Retry-After seconds; you account for the application limits, which all its users share.
• You account for the rate limit on the auth endpoints and for the content creation quota.
• You treat a 400 as an error in how the request is built, not as an outage.
• You expect other users' personal data to arrive empty or masked.

Calling from a server versus a browser

	From a server	From a browser
CORS	does not apply	you must be on the list
Application key	in the header, secret	in the header, not secret (anyone can extract it)
Token	in the header	in the header
Retry-After	you can read it	you cannot — the header is not exposed; read data.retryAfter from the body

Cookie settings