Getting started#

From scratch to your first request.

curl -X POST https://your-site.com/api/system/auth/login \
  -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,
  "exception": null,
  "data": {
    "user": { },
    "token": "<access token>",
    "refreshToken": "<refresh token>",
    "payload": { }
  },
  "code": 0
}

2. Make your first read#

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

Without computeTotalCount=1 the totalCount is zero

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

3. Unwrap the response#

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

4. Refresh the token#

An access token lasts 15 minutes. Then:

curl -X POST https://your-site.com/api/system/auth/refresh \
  -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#

Parameters go in the URL, not the body.
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.
Your domain is on the allowed origins list.
You account for the rate limit on the auth endpoints.

Calling from a server versus a browser#

	From a server	From a browser
CORS	does not apply	you must be on the list
Token	in the header	in the header
`Retry-After`	you can read it	you cannot — the header is not exposed