Authentication

One call in, a bearer token out.

Get a token

$BASE is your tenant’s API root, https://<tenant>-api.mathfi.ai. It is issued with your account and differs per customer, so take it as configuration rather than hard-coding it.

BASE="https://<tenant>-api.mathfi.ai"

curl -s -X POST "$BASE/api/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"[email protected]","password":"YOUR_PASSWORD"}'

{
  "username": "[email protected]",
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

The field is username, and it holds your email address. This trips up nearly everyone on the first call.

Wrong credentials give 401 with no body worth parsing.

Use it

curl -s -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/v1/datasets?offset=0&limit=10"

Every /api/v1/** endpoint needs it. /api/login does not. Never send it to a signed upload URL. Those URLs carry their own signature, and an extra Authorization header invalidates it. You get 403 SignatureDoesNotMatch and it is not obvious why.

Lifetime


Idle window	60 minutes
Absolute cap	24 hours from login

The window slides: each authenticated request pushes expiry forward, so an active client stays signed in. An idle one lapses after an hour. Either way the session ends 24 hours after login and you log in again. This matters for long jobs. A Feature Refinery run can outlive an idle token, so a client that starts a run and then sleeps for an hour will wake up to 401. Either keep polling, which slides the window, or re-authenticate on 401.

No API keys

There are none today. Service-to-service callers use the same email and password flow, with a dedicated account. Store credentials outside your code. Environment variables, a secret manager, a keychain, whichever your environment provides. A CLI or agent built from these docs should take credentials as parameters and never write them to disk in plain text.

Handling expiry

The pattern any client should implement:

#!/usr/bin/env bash
set -euo pipefail

: "${MATHFI_BASE_URL:?set MATHFI_BASE_URL, e.g. https://<tenant>-api.mathfi.ai}"
: "${MATHFI_EMAIL:?set MATHFI_EMAIL}"
: "${MATHFI_PASSWORD:?set MATHFI_PASSWORD}"
BASE="$MATHFI_BASE_URL"

login() {
  curl -sS -X POST "$BASE/api/login" \
    -H "Content-Type: application/json" \
    -d "{\"username\":\"$MATHFI_EMAIL\",\"password\":\"$MATHFI_PASSWORD\"}" \
    | jq -r .access_token
}

TOKEN=$(login)

# Call, and re-authenticate once on 401.
api() {
  local method=$1 path=$2; shift 2
  local out code
  out=$(curl -sS -w '\n%{http_code}' -X "$method" "$BASE$path" \
        -H "Authorization: Bearer $TOKEN" "$@")
  code=$(tail -n1 <<<"$out")
  if [[ $code == 401 ]]; then
    TOKEN=$(login)
    out=$(curl -sS -w '\n%{http_code}' -X "$method" "$BASE$path" \
          -H "Authorization: Bearer $TOKEN" "$@")
    code=$(tail -n1 <<<"$out")
  fi
  [[ $code == 2* ]] || { echo "HTTP $code: $(sed '$d' <<<"$out")" >&2; return 1; }
  sed '$d' <<<"$out"
}

api GET "/api/v1/datasets?offset=0&limit=10" | jq '.total'

Retry a 401 once. If the second attempt also fails, the credentials are wrong, not the token.

Recipes

Full flows built on this helper.

Getting started

Feature Refinery

Model Crucible

Authentication

Get a token

Use it

Lifetime

No API keys

Handling expiry

Recipes

​Get a token

​Use it

​Lifetime

​No API keys

​Handling expiry

Recipes

Get a token

Use it

Lifetime

No API keys

Handling expiry