Quickstart

Get up and running with the Monogoto API in under 10 minutes. By the end of this guide you will have authenticated, made your first live API call, and understand how to handle the response.

Overview

The Monogoto API is a RESTful HTTP API. All requests are made to https://api.monogoto.io and all request/response bodies use JSON. The typical integration flow is:

1. Authenticate — exchange credentials for a short-lived access token
2. Call endpoints — pass the token in the Authorization header on every request
3. Refresh proactively — use the refresh token to get a new access token before it expires
4. Handle errors — inspect the structured error response and retry where appropriate

No Sandbox — All Calls Are Live

Monogoto does not currently offer a sandbox or test environment. Every API call — including those made through the Try It console in this documentation — is executed against your live account and affects real data: SIM states, network policies, billing, and so on.

Before running any write operation (POST, PUT, PATCH, DELETE), confirm that you are comfortable with its effect on production resources. There is no way to roll back most mutations through the API.

Prerequisites

Before you begin, make sure you have:

• A Monogoto account (sign up at monogoto.io)
• Your login credentials (email + password)
• curl, Postman, or any HTTP client / SDK

Step 1: Authenticate

All API requests require a Bearer token. Obtain one by posting your credentials to the auth endpoint.

curl -X POST https://api.monogoto.io/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your@email.com",
    "password": "your-password"
  }'

A successful response returns three fields:

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Security note: Store tokens in environment variables or a secrets manager — never hard-code them in source files or commit them to version control.

Step 2: Make Your First API Call

Pass the access token in the Authorization header on every request. Here we list all SIM cards (Things) on your account:

curl https://api.monogoto.io/v1/things \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

A successful 200 OK response looks like:

{
  "items": [
    {
      "iccid": "89370100002471565102",
      "name": "Device-001",
      "status": "active"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

Tip: Copy your access token into the ENV Vars panel in the API Reference and set a variable like ACCESS_TOKEN. All Try It consoles on this site will automatically inject it into the Authorization header.

Step 3: Keep Your Token Fresh

Access tokens expire after 4 hours. Rather than re-entering credentials, use the refresh token to silently obtain a new pair:

curl -X POST https://api.monogoto.io/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

The response is identical to the login response — you receive a fresh access_token and a new refresh_token (the previous one is immediately invalidated). Update both stored values after every refresh.

Step 4: Handle Errors

All errors use a consistent JSON shape:

{
  "status_code": 401,
  "message": "Token has expired or is invalid",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

The key fields to act on:

A minimal resilient client in JavaScript:

const BASE_URL = 'https://api.monogoto.io';

async function apiFetch(path, options = {}) {
  const res = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${getStoredAccessToken()}`,
      ...options.headers,
    },
  });

  if (res.ok) return res.json();

  const error = await res.json().catch(() => ({ message: res.statusText }));

  if (res.status === 401) {
    // Token expired — refresh and retry once
    await refreshAccessToken();
    return apiFetch(path, options);
  }

  if (res.status === 429) {
    const wait = parseInt(res.headers.get('Retry-After') ?? '60', 10) * 1000;
    await new Promise(r => setTimeout(r, wait));
    return apiFetch(path, options);
  }

  throw Object.assign(new Error(error.message), {
    statusCode: error.status_code,
    requestId: error.request_id,
  });
}

Full Working Example

The following script authenticates, fetches your SIM list, and handles token expiry — everything you need to validate your credentials end-to-end.

BASE_URL = "https://api.monogoto.io"

class MonogotoClient:
    def __init__(self, username: str, password: str):
        self.username = username
        self.password = password
        self._access_token: str | None = None
        self._refresh_token: str | None = None
        self._token_expires_at: float = 0

    def _login(self):
        resp = requests.post(f"{BASE_URL}/v1/auth/token", json={
            "username": self.username,
            "password": self.password,
        })
        resp.raise_for_status()
        data = resp.json()
        self._store_tokens(data)

    def _refresh(self):
        resp = requests.post(f"{BASE_URL}/v1/auth/refresh", json={
            "refresh_token": self._refresh_token,
        })
        if resp.status_code == 401:
            # Refresh token expired — fall back to full login
            self._login()
            return
        resp.raise_for_status()
        self._store_tokens(resp.json())

    def _store_tokens(self, data: dict):
        self._access_token = data["access_token"]
        self._refresh_token = data["refresh_token"]
        # Refresh proactively 5 minutes before expiry
        self._token_expires_at = time.time() + (4 * 3600) - 300

    def _ensure_token(self):
        if not self._access_token:
            self._login()
        elif time.time() >= self._token_expires_at:
            self._refresh()

    def get(self, path: str) -> dict:
        self._ensure_token()
        resp = requests.get(f"{BASE_URL}{path}", headers={
            "Authorization": f"Bearer {self._access_token}"
        })
        resp.raise_for_status()
        return resp.json()


if __name__ == "__main__":
    client = MonogotoClient(
        username=os.environ["MONOGOTO_USER"],
        password=os.environ["MONOGOTO_PASS"],
    )
    sims = client.get("/v1/things")
    print(f"Found {sims['total']} SIM(s):")
    for sim in sims["items"]:
        print(f"  {sim['iccid']}  {sim['name']}  [{sim['status']}]")

Run it with:

MONOGOTO_USER=your@email.com MONOGOTO_PASS=your-password python quickstart.py

Next Steps