​
Overview

We use Bearer token authentication to secure all API requests.
Every request to the API must include a valid bearer token in the Authorization header, along with a Monime-Space-Id header that identifies which Space you’re operating in. This dual-header approach creates a powerful security model where tokens provide identity and authentication, while Space IDs provide context and isolation. 
curl -X GET https://api.monime.io/v1/financial-accounts \
  --header "Authorization: Bearer <access-token>" \
  --header "Monime-Space-Id: <monime-space-id>"
Tokens are owned by a Monimeer (user) and are space-agnostic by design; effective access comes from the intersection of the token’s scopes and the Monimeer’s role in the Space you target.

​
Quick Token Test

You can sanity-check a token by hitting the root endpoint. The response echoes whether you’re authenticated, which environment you’re in, and what Monime sees as your origin. 
GET https://api.monime.io

​
1) Not Authenticated

curl -X GET https://api.monime.io \
  -H "Accept: application/json"
Response: 
{
  "platform": "Monime - Ⓜ️",
  "tagline": "APIs Beyond Payments ⚡️⚙️💰️",
  "status": {
    "environment": null,
    "isAuthenticated": false
  },
  "apiVersion": null,
  "requestOrigin": {
    "country": "SL",
    "ipAddress": "2c0f:2a80:4ea:1f08:2c1b:e667:f921:ddcf"
  }
}
What this tells you:
  • ❌ isAuthenticated: false - Token is missing, invalid, or expired
  • ❌ environment: null - Cannot determine environment without valid token
  • ❌ apiVersion: null -Cannot determine API version.

​
2) Authenticated with Test Token

curl -s https://api.monime.io \
  -H "Accept: application/json" \
  -H "Authorization: Bearer mon_test_XXXXXXXXXXXXXXXX"
Response: 
{
    "platform": "Monime - Ⓜ️",
    "tagline": "APIs Beyond Payments ⚡️⚙️💰️",
    "status": {
        "environment": "test",
        "isAuthenticated": true
    },
    "apiVersion": {
        "id": "caph.2025-08-23",
        "release": {
            "name": "caph",
            "date": "2025-06-20"
        },
        "deprecated": false,
        "apiSchemas": {
            "openApi": "https://github.com/monimesl/monime-developer-apis/blob/main/api-versions/-/specifications/openapi.yaml"
        }
    },
    "requestOrigin": {
        "country": "SL",
        "ipAddress": "2c0f:2a80:4ea:1f08:2c1b:e667:f921:ddcf"
    }
}
What this tells you:
  • ✅ isAuthenticated: true - Valid test token
  • ✅ environment: "test" - Connected to test environment
  • ✅ apiVersion - Current API version you’re accessing
  • ⚠️ Safe for testing - No real money moves in test environment

​
3) Authenticated with Live Token

curl -s https://api.monime.io \
  -H "Accept: application/json" \
  -H "Authorization: Bearer mon_XXXXXXXXXXXXXXXX"
Response: 
{
    "platform": "Monime - Ⓜ️",
    "tagline": "APIs Beyond Payments ⚡️⚙️💰️",
    "status": {
        "environment": "live",
        "isAuthenticated": true
    },
    "apiVersion": {
        "id": "caph.2025-08-23",
        "release": {
            "name": "caph",
            "date": "2025-06-20"
        },
        "deprecated": false,
        "apiSchemas": {
            "openApi": "https://github.com/monimesl/monime-developer-apis/blob/main/api-versions/-/specifications/openapi.yaml"
        }
    },
    "requestOrigin": {
        "country": "SL",
        "ipAddress": "2c0f:2a80:4ea:1f08:2c1b:e667:f921:ddcf"
    }
}
What this tells you:
  • ✅ isAuthenticated: true - Valid test token
  • ✅ environment: "live" - Connected to production environment
  • ✅ apiVersion - Current API version you’re accessing
  • 🚀 Production mode - Real financial transactions will occur

​
Security best practices

  • Server-Side Only: Never expose tokens in browsers or mobile apps.
  • Least-Privilege Scopes: Grant a token only the roles the job needs.
  • One Token per Integration: Use separate tokens per service/use-case (single responsibility).
  • Rotate & Revoke Fast: Rotate on a schedule; revoke immediately if leaked or unused.
  • Secure Storage: Keep tokens in a secrets manager (Vault/AWS/GCP/K8s secret); never hardcode or store in plain .env file in production.
  • No Logging: Mask/redact tokens in logs, metrics, traces, and error messages.
  • Ownership: Name tokens clearly (owner, purpose, scope) and review them regularly.
  • Limited Lifetime: Prefer shorter expirations or scheduled rotation windows.
  • Usage Boundaries: Restrict where tokens can be used (e.g., IP whitelisting, Space whitelisting).

​
Common errors & fixes

  • 401 Unauthorized
    • Cause: Missing/invalid/expired access token.
    • Fix: send a valid and active access token.
  • 403 Forbidden
    • Cause: Token valid, but with insufficient permission or owner has no access to the space.
    • Fix: Grant the needed persmission or adjust the monimeer’s Space role.