Mad Fish Elements
HomeTrust CenterAPI authentication

API authentication

Create and maintain a session with the Mad Fish Elements API using account credentials and the returned session cookie.

Authentication endpointPOST https://api.madfishelements.com/auth/login
Authentication methodHTTP Basic credentials + session cookie
Create an authenticated API session

Send your Mad Fish Elements account email and password as HTTP Basic credentials over HTTPS. A successful login returns account details as JSON and sets the session cookie used to authorize subsequent calls to the Objects API.

The request is form encoded rather than raw JSON. Serialize the JSON request object into the field named request, save the response cookie, and reuse that cookie until it expires or you log out.

Authentication flow

1. Send Basic credentials

Use the account email as the username and the account password as the password. Never place either value in a URL or source-controlled file.

2. Save the session cookie

The cookie arrives in the HTTP Set-Cookie response header. It is not returned inside the JSON response body.

3. Reuse the authenticated session

Send the stored cookie with each /objects/* request. If the session expires, authenticate again and replace the old cookie.

4. End the session

Send the cookie to GET /auth/logout, then remove the cookie from your client. The current API may return HTTP 500 with a JSON error for invalid credentials or an expired session.

JSON request bodyrequest field
{}

This empty JSON object is the value of the form-encoded request field. Credentials are carried by the HTTP Basic authorization header.

JSON response body200 OK
{
  "user": {
    "id": 583,
    "username": "Taylor Example",
    "email": "taylor@example.com",
    "last_login": "2026-08-07 10:14:22",
    "token": "account-token-value",
    "authorized_reports": [
      {
        "id": 123,
        "url": "https://example.com",
        "url_name": "Example"
      }
    ]
  }
}

Representative response. Account-specific fields and entries in authorized_reports vary by user type and permissions.

cURL requestShell
export MFE_EMAIL='you@example.com'
export MFE_PASSWORD='your-password'

curl -sS -c mfe-api.cookies \
  -u "$MFE_EMAIL:$MFE_PASSWORD" \
  -X POST https://api.madfishelements.com/auth/login \
  --data-urlencode 'request={}'

The -c option writes the returned session cookie to mfe-api.cookies. Keep that file private.

Python requestrequests
import json
import os
import requests

session = requests.Session()
response = session.post(
    "https://api.madfishelements.com/auth/login",
    auth=(os.environ["MFE_EMAIL"], os.environ["MFE_PASSWORD"]),
    data={"request": json.dumps({})},
    timeout=30,
)
response.raise_for_status()
print(response.json())

# Reuse this session for every Objects API request.

Install the client with python -m pip install requests. Reuse the same Session object for API calls.

Explore the available endpoints

Return to the API reference for reporting endpoints, request fields, and response conventions.

API reference