> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monime.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How clients prove identity and gain the right access

# 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.

```shell theme={null}
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.

```text theme={null}
GET https://api.monime.io
```

### 1) Not Authenticated

```shell theme={null}
curl -X GET https://api.monime.io \
  -H "Accept: application/json"
```

**Response:**

```json theme={null}
{
  "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

```shell theme={null}
curl -s https://api.monime.io \
  -H "Accept: application/json" \
  -H "Authorization: Bearer mon_test_XXXXXXXXXXXXXXXX"
```

**Response:**

```json theme={null}
{
    "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

```shell theme={null}
curl -s https://api.monime.io \
  -H "Accept: application/json" \
  -H "Authorization: Bearer mon_XXXXXXXXXXXXXXXX"
```

**Response:**

```json theme={null}
{
    "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.