Skip to main content
The NodeForgeCMS API uses JSON Web Tokens (JWT) for authentication. To authenticate, exchange your username and password for a token via the login endpoint, then attach that token to every subsequent request that requires authorisation. Public read endpoints do not require a token; all write operations (POST, PUT, PATCH, DELETE) do.

​
Getting a Token

Send a POST request to /api/auth/login with your credentials in the request body.

​
Request Body Parameters

​
username
string
required
Your NodeForgeCMS admin username.
​
password
string
required
Your NodeForgeCMS admin password.

​
Login Request

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your_password"
}

​
Successful Response

On success, the API returns a 200 response containing your JWT token and basic information about the authenticated user: 
{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin",
      "role": "admin"
    }
  },
  "message": "success"
}
FieldTypeDescription
data.tokenstringThe JWT Bearer token to use in subsequent requests
data.user.idintegerUnique identifier of the authenticated user
data.user.usernamestringUsername of the authenticated user
data.user.rolestringRole assigned to the user (admin or editor)
Store the token value securely — you’ll include it in the Authorization header of every authenticated request.

​
Using the Token

Once you have a token, pass it in the Authorization header as a Bearer token on every request that requires authentication: 
GET /api/articles
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

​
curl Example

curl -X GET https://yourdomain.com/api/articles \
  -H "Authorization: Bearer YOUR_TOKEN"
Replace YOUR_TOKEN with the full token string returned from the login endpoint. The Bearer prefix (with the trailing space) is required.
Never expose your token in client-side code, public repositories, or logs. Treat it with the same care as a password. If a token is compromised, re-authenticate to obtain a new one.

​
Token Expiry

Tokens expire after a configured period defined in your NodeForgeCMS server settings. When a token expires, the API will reject it with a 401 Unauthorized response: 
{
  "code": 401,
  "message": "Token expired"
}
When this happens, re-authenticate by calling POST /api/auth/login again with your credentials to obtain a fresh token. There is no refresh-token mechanism — each new session requires a full login.

​
Error Responses

CodeErrorDescription
401UnauthorizedThe Authorization header is missing, the token is malformed, or the token has expired.
403ForbiddenThe token is valid and the user is authenticated, but the user’s role does not have permission to perform the requested operation.

​
401 Example — Missing or Invalid Token

{
  "code": 401,
  "message": "Unauthorized: invalid or missing token"
}

​
403 Example — Insufficient Permissions

{
  "code": 403,
  "message": "Forbidden: you do not have permission to perform this action"
}
If you receive a 403, check that the authenticated user has the appropriate role for the operation. Certain endpoints — such as user administration — may be restricted to users with the admin role only.