Offentligt API & API-nycklar

1. Översikt

Med MousePlayers API hämtar du data från arbetsytan till egna dashboarder, datalager eller interna verktyg. Förutom att koppla kund-ID:n till sessioner (identify, kräver en nyckel med skrivbehörighet, se Nyckelbehörigheter) ger det endast läsåtkomst: inga data kan ändras eller raderas via API:et.

• Bas-URL: https://www.mouseplayer.com/api/v1/
• Alla svar är JSON.
• Varje anrop autentiseras med en API-nyckel och begränsas automatiskt till arbetsytan som nyckeln tillhör — en nyckel från en arbetsyta kan aldrig se en annan arbetsytas data, inte ens av misstag.
• Hela sessionsinspelningen (musrörelser, DOM-ögonblicksbilder) är inte tillgänglig via API:et. Du får sessionsmetadata, sidvisningar, anpassade händelser och segment — tillräckligt för rapporter och dashboarder utan att flytta runt råa uppspelningsdata.

2. Autentisering

Skapa och hantera API-nycklar under API-nycklar i kontomenyn (/api-keys). Bara arbetsytans ägare och administratörer kan skapa eller återkalla nycklar.

Skicka nyckeln som en Bearer-token i huvudet Authorization i varje anrop:

Saknade, felaktiga eller återkallade nycklar får svaret 401:

Abonnemangskrav

REST-API:et ingår i abonnemangen Business och Enterprise. Abonnemanget hämtas från arbetsytans ägare, så inbjudna teammedlemmar ärver det. Kontrollen görs vid varje anrop, inte bara när nyckeln skapas — om arbetsytan nedgraderas slutar befintliga nycklar fungera och returnerar 403.

Nyckelbehörigheter

Varje nyckels behörighet framgår av prefixet, så du ser vad den får göra bara genom att titta på den — i en .env, i ett ärende eller i en terminal.

3. Anropsgränser

Varje API-nyckel är begränsad till 60 anrop per minut, mätt i ett rullande tidsfönster. När gränsen överskrids får anrop svaret 429 tills tidsfönstret frigörs:

4. Slutpunkter

GET/api/v1/projects

Listar varje projekt (spårad webbplats) i arbetsytan.

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

Listar besökarsessioner inspelade för ett projekt, nyast först. Sidindelat.

GET/api/v1/sessions/{session_id}

Metadata för en session samt dess sidvisningar. Fullständiga uppspelningsdata utelämnas avsiktligt — använd spelaren i dashboarden för dem.

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

Anpassade händelser som utlösts under en session (samma händelser som du skickar med mp('event', ...)), inklusive parametrar.

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

Listar besökarsegmenten för ett projekt, både projektspecifika och gemensamma för arbetsytan.

5. Koppla ett kund-ID från din backend

Webbläsaren vet ofta inte vem som sitter där. I en B2B-produkt fastställs identiteten efter inloggning — i din backend. I en butik sker det vid orderbekräftelsen. Slutpunkten är till för just det ögonblicket.

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}}

ID:t visas sedan i sessionslistan, är sökbart där och webhooken session_identified utlöses — så når det ditt CRM.

6. Webhookar: verifiera signaturen

Webhookar konfigureras per projekt under Integrationer, där även signeringshemligheten finns. Varje leverans har följande huvuden:

Signaturen är en HMAC-SHA256 över timestamp + "." + raw body, med projektets signeringshemlighet som nyckel.

// 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');

Leverans och återförsök

En misslyckad leverans görs om efter 1 min, 5 min, 15 min, 1 h och 6 h, sedan avslutas försöken. 4xx-svar, utom 408 och 429, görs inte om — de betyder "inte så här", inte "inte just nu". Svara 2xx snabbt och gör arbetet efteråt. Leveransen avbryts efter 10 sekunder.

Tillgängliga händelser

7. Fel & statuskoder

8. Säkerhetsinformation

• Läsnycklar (mp_ro_) kan inte ändra något. Skrivnycklar (mp_rw_) kan bara koppla kund-ID:n. Ingen nyckel kan radera data eller exportera råa uppspelningsdata.
• Varje anrop begränsas automatiskt till nyckelns egen arbetsyta — det går inte att ange ett annat arbetsyte-ID och se någon annans data.
• Återkalla en nyckel när som helst från /api-keys. Återkallandet gäller omedelbart.
• Behandla API-nyckeln som ett lösenord. Om du av misstag committar den till ett offentligt kodarkiv återkallar du den direkt och skapar en ny.