Authentication

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 $MONIME_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 - The API version you're using: id is the version, such as caph.2025-08-23, and release.date is when its release, caph, began
• ⚠️ 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 live token
• ✅ environment: "live" - Connected to production environment
• ✅ apiVersion - The API version you're using: id is the version, such as caph.2025-08-23, and release.date is when its release, caph, began
• 🚀 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.