Openbare API & API-sleutels

1. Overzicht

Met de MousePlayer-API haalt u gegevens uit uw werkruimte op voor uw eigen dashboards, datawarehouse of interne tools. Afgezien van het koppelen van klant-ID’s aan sessies (identify, waarvoor een sleutel met schrijfrechten nodig is; zie Sleutelbereik) is deze alleen-lezen: er kunnen geen gegevens via de API worden gewijzigd of verwijderd.

• Basis-URL: https://www.mouseplayer.com/api/v1/
• Alle antwoorden zijn JSON.
• Elk verzoek wordt met een API-sleutel geauthenticeerd en automatisch beperkt tot de werkruimte waartoe die sleutel behoort — een sleutel uit de ene werkruimte kan nooit gegevens uit een andere zien, ook niet per ongeluk.
• De volledige sessie-opname (muisbewegingen, DOM-momentopnamen) is niet beschikbaar via de API. U krijgt sessiemetadata, paginaweergaven, aangepaste gebeurtenissen en segmenten — genoeg om rapporten en dashboards te bouwen zonder de ruwe opnamegegevens rond te sturen.

2. Authenticatie

Maak en beheer uw API-sleutels onder API-sleutels in uw accountmenu (/api-keys). Alleen eigenaren en beheerders van de werkruimte kunnen sleutels maken of intrekken.

Stuur de sleutel als Bearer-token mee in de Authorization header van elk verzoek:

Ontbrekende, onjuist gevormde of ingetrokken sleutels krijgen een 401 antwoord:

Vereist abonnement

De REST-API is beschikbaar bij Business en Enterprise . Het abonnement van de eigenaar van de werkruimte is bepalend, dus uitgenodigde teamleden erven dit. De controle vindt plaats bij elk verzoek, niet alleen bij het maken van een sleutel — als een werkruimte naar een lager abonnement gaat, werken bestaande sleutels niet meer en retourneren ze 403.

Sleutelbereik

Elke sleutel vermeldt het bereik in zijn eigen prefix. U ziet dus meteen wat een sleutel kan — in een .env, een ticket of een terminal.

3. Verzoeklimieten

Elke API-sleutel is beperkt tot 60 verzoeken per minuut, bijgehouden in een voortschrijdend tijdvenster. Zodra u dit overschrijdt, krijgen verzoeken een 429 antwoord totdat er weer ruimte in het tijdvenster is:

4. Endpoints

GET/api/v1/projects

Toont alle projecten (gevolgde property’s) in uw werkruimte.

GET/api/v1/projects/{channelid}/sessions

Toont opgenomen bezoekerssessies voor een project, de nieuwste eerst. Met paginering.

GET/api/v1/sessions/{session_id}

Metadata van één sessie, inclusief de paginaweergaven. De volledige opnamegegevens zijn bewust uitgesloten — gebruik daarvoor de speler in het dashboard.

GET/api/v1/sessions/{session_id}/events

Aangepaste gebeurtenissen die tijdens een sessie zijn geactiveerd (dezelfde die u verstuurt met mp('event', ...)), inclusief hun parameters.

GET/api/v1/projects/{channelid}/segments

Toont de bezoekerssegmenten die voor een project zijn gedefinieerd, zowel projectspecifieke als werkruimtebrede segmenten.

5. Een klant-ID koppelen vanuit uw backend

De browser weet vaak niet wie erachter zit. Bij een B2B-product wordt de identiteit na het inloggen vastgesteld — in uw backend. Bij een winkel gebeurt dat bij de bestelbevestiging. Dit endpoint is precies voor dat moment.

POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json

{"user_id": "customer-4711"}

// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
          "changed": true, "previous": null, "webhook_queued": true}}

De ID verschijnt vervolgens in de sessielijst, is daar doorzoekbaar en de webhook session_identified wordt geactiveerd — zo bereikt de informatie uw CRM.

6. Webhooks: de handtekening controleren

Webhooks worden per project ingesteld onder Integraties, waar u ook het ondertekeningsgeheim vindt. Elke aflevering bevat deze headers:

De handtekening is een HMAC-SHA256 over timestamp + "." + raw body, met het ondertekeningsgeheim van uw project als sleutel.

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; }

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
                                     .update(timestamp + '.' + rawBody).digest('hex');

Aflevering en nieuwe pogingen

Een mislukte aflevering wordt opnieuw geprobeerd na 1 min, 5 min, 15 min, 1 uur en 6 uur, daarna wordt gestopt. Antwoorden met status 4xx anders dan 408 en 429 worden niet opnieuw geprobeerd — ze betekenen "niet op deze manier", in plaats van "niet op dit moment". Antwoord snel met 2xx en voer het werk daarna uit; de aflevering verloopt na 10 seconden.

Beschikbare gebeurtenissen

7. Fouten & statuscodes

8. Beveiligingsopmerkingen

• Alleen-lezen sleutels (mp_ro_) kunnen niets wijzigen. Schrijfsleutels (mp_rw_) kunnen alleen klant-ID’s koppelen; geen enkele sleutel kan gegevens verwijderen of ruwe opnamegegevens exporteren.
• Elk verzoek wordt automatisch beperkt tot de eigen werkruimte van de sleutel — u kunt geen andere werkruimte-ID meegeven om gegevens van iemand anders te zien.
• Trek een sleutel op elk moment in via /api-keys; dit gaat onmiddellijk in.
• Behandel uw API-sleutel als een wachtwoord. Als u er per ongeluk een in een openbare repository commit, trekt u deze direct in en maakt u een nieuwe.