Skip to main content

Mango REST API Authentication

Mango uses session-based authentication with CSRF (Cross-Site Request Forgery) protection for its REST API. This page explains how to authenticate, manage sessions, and handle CSRF tokens when making API requests.

Authentication Methods​

Mango supports the following authentication approaches:

MethodUse CaseDetails
Session + CSRFBrowser-based and scripted clientsLogin via POST, maintain session cookie
JWT TokensService-to-service or long-lived tokensIssued via the auth-token endpoints
Basic AuthSimple scripts (when enabled)Username/password in Authorization header

Session-Based Authentication with CSRF/XSRF Protection​

Mango uses a stateless double-submission CSRF/XSRF protection mechanism. This means that you can generate the initial XSRF token value on the client side and it is unnecessary to perform an initial request just to get the XSRF-TOKEN cookie value.

If you generate the token value this way, you should use a secure (cryptographically strong) random generation method and keep the token secret.

It is still necessary to read the session cookie from the Set-Cookie header when logging in and send this back to Mango in the Cookie header for subsequent requests.

How CSRF Protection Works​

  1. Generate a random XSRF token value on the client side (or obtain one from Mango).
  2. Send this token as both a cookie (XSRF-TOKEN) and a header (X-XSRF-TOKEN) with every request.
  3. Mango verifies that both values match, confirming the request is legitimate.

Login (Mango v4+)​

  • Login URL is /rest/latest/login
  • The Login HTTP method is POST
  • Login sends the username and password as JSON in the request body
  • CSRF protection uses a stateless double-submit mechanism where the X-XSRF-TOKEN header value must match the value in the Cookie header

Example Login​

Request​

POST /rest/latest/login HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json;charset=UTF-8
Cookie: XSRF-TOKEN=74cf354a-e871-48b6-a1c2-bebb93d00120
X-XSRF-TOKEN: 74cf354a-e871-48b6-a1c2-bebb93d00120
Content-Length: 39

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

Response​

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Set-Cookie: <Mango GUID>=<Cookie Name>
Set-Cookie: XSRF-TOKEN=072a9aa4-7998-485c-8b53-a7dd7dcbc3e7;Path=/

{
    "username": "admin",
    "email": "admin@example.com",
    "permissions": ["superadmin"],
    ...
}

After a successful login, save the session cookie and the new XSRF token from the response. Use them in all subsequent API requests.

Example Login with curl​

Here is a complete example using curl to log in and then make an authenticated request:

# Step 1: Generate a random XSRF token
XSRF_TOKEN=$(uuidgen)

# Step 2: Login and capture cookies
curl -c cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $XSRF_TOKEN" \
  -b "XSRF-TOKEN=$XSRF_TOKEN" \
  -d '{"username": "admin", "password": "admin"}' \
  http://localhost:8080/rest/latest/login

# Step 3: Make an authenticated request (read XSRF token from cookie file)
NEW_XSRF=$(grep XSRF-TOKEN cookies.txt | awk '{print $NF}')
curl -b cookies.txt \
  -H "X-XSRF-TOKEN: $NEW_XSRF" \
  http://localhost:8080/rest/latest/data-points?limit(10)

JWT Token Authentication​

For service-to-service integrations or scenarios where session management is impractical, Mango supports JWT (JSON Web Token) authentication. JWT tokens can be created through the REST API and included in the Authorization header:

Authorization: Bearer <jwt-token>

JWT tokens have a configurable expiration time and can be revoked by an administrator.

Logout​

To end a session, send a POST request to the logout endpoint:

POST /rest/latest/logout

This invalidates the session cookie on the server side.

  • REST API Overview — Introduction to the Mango REST API, base URL, and Swagger UI
  • API Examples — Practical examples of authenticated API requests
  • RQL Queries — Query syntax for filtering and paginating API results