Skip to content

API reference / RivetIT

RivetIT API

v1.0.0 141 endpoints OpenAPI 3

Companion REST API for RivetIT, consumed by the RivetIT mobile app and other integrations (RMM scripts and the like). This spec documents the live endpoints served by /api/v1/index.php and its per-resource handlers.

Authentication. There are two kinds of credential:

  • API keys (machines; the primary method: a Client ID + secret). Create a client under Administration > API Keys, exchange its Client ID and secret at POST /oauth/token (OAuth2 client credentials) for a 10 minute signed access token and send it as Authorization: Bearer <access token>. A token reaches a route only if it holds that route's scope (api:<resource>:read|write|delete, lms:*, directory:read); there is no wildcard, and the client's department scope applies. It never acts as a user or an administrator.

  • User session tokens (a signed-in person, e.g. the mobile app): a bearer token issued by POST /auth. Unrelated to integration clients and unchanged.

The old X-Api-Key header (legacy API keys) is not accepted any more: a request that sends it without a valid token is answered 401 with a message pointing at POST /oauth/token. Existing integrations must switch to an API key's Client ID + secret. The /auth, /branding, /openapi and /docs endpoints are public (no token required).

Response conventions:

  • Paged list endpoints return { "data": [ ... ], "total": <int> } (some also add page/limit).
  • Some list endpoints return a bare JSON array (noted per-endpoint).
  • Creates return { "id": <int> } (sometimes with extra fields).
  • Simple mutations return { "ok": true }.
  • Errors return { "error": "<message>" } with the matching HTTP status.

Base URL and authentication

Requests go to https://YOUR-HOST/api/v1, where YOUR-HOST is your own install.

Quick start

  1. 1Get a token

    Password login — returns a bearer token, or requires_2fa. Keep the token and send it as a bearer token on every call.

    curl -X POST "https://YOUR-HOST/api/v1/auth" \
      -H "Content-Type: application/json" \
      -d '{"username":"string","password":"string"}'
    import requests
    
    response = requests.post(
        "https://YOUR-HOST/api/v1/auth",
        json={
            "username": "string",
            "password": "string"
        },
    )
    print(response.json())
    const response = await fetch("https://YOUR-HOST/api/v1/auth", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
          "username": "string",
          "password": "string"
      }),
    });
    const data = await response.json();
    $ch = curl_init("https://YOUR-HOST/api/v1/auth");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
        CURLOPT_POSTFIELDS => '{"username":"string","password":"string"}',
    ]);
    $data = json_decode(curl_exec($ch), true);
    Example response
    json
    {
        "token": "string",
        "user": {
            "id": 1,
            "name": "string",
            "email": "string",
            "type": 1
        }
    }
  2. 2Make your first request

    List tickets. Replace TOKEN with the token from step 1.

    curl "https://YOUR-HOST/api/v1/tickets" \
      -H "Authorization: Bearer $TOKEN"
    import requests
    
    response = requests.get(
        "https://YOUR-HOST/api/v1/tickets",
        headers={"Authorization": f"Bearer {TOKEN}"},
    )
    print(response.json())
    const response = await fetch("https://YOUR-HOST/api/v1/tickets", {
      method: "GET",
      headers: { "Authorization": `Bearer ${TOKEN}` },
    });
    const data = await response.json();
    $ch = curl_init("https://YOUR-HOST/api/v1/tickets");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => "GET",
        CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
    ]);
    $data = json_decode(curl_exec($ch), true);

Find an endpoint

Resources