ISIRO
Må vi måle, om vores annoncer virker?

ISIRO bruger Google Ads og vil gerne vide, om en annonce bliver til en kunde. Det kræver en cookie, der ikke er nødvendig for, at siden virker — og derfor spørger vi, før vi gør det.

Siger du nej, sker der ingenting. Vi husker dit nej i din browser, så du ikke bliver spurgt igen, og det er det eneste, vi gemmer. Du kan skifte mening når som helst nederst på siden.

Læs mere i cookiepolitikken

Dokumentation

ISIRO har fem kald. Alle adresser herunder er relative til ISIROs adresse.

Godkendelse med API-nøgle

Alle kald skal sende API-nøglen i headeren:

Authorization: Bearer <din API-nøgle>

Du opretter nøgler i portalen under API-nøgler. Den fulde nøgle vises kun én gang, når den oprettes. ISIRO gemmer kun en hash af nøglen og kan derfor ikke vise den igen. Mister du den, må du oprette en ny og tilbagekalde den gamle.

Alle kald skal bruge POST, og kroppen skal være et JSON-objekt med Content-Type: application/json. Svaret er altid JSON.

Opret slutbruger

POST /api/v1/bruger-opret.php

Felter ind

Felter ud (HTTP 201)

Brugeren er ikke bekræftet, før den første rigtige kode er godkendt.

Eksempel

POST /api/v1/bruger-opret.php
Authorization: Bearer isk_Ab12Cd34_...
Content-Type: application/json

{"ekstern_id": "bruger-4711", "kontonavn": "anne@firma.dk", "udsteder": "Firma ApS"}
HTTP 201
{
  "ok": true,
  "slutbruger_id": "bruger-4711",
  "hemmelighed": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
  "otpauth_uri": "otpauth://totp/Firma%20ApS:anne%40firma.dk?secret=...&issuer=Firma%20ApS&algorithm=SHA1&digits=6&period=30",
  "gendannelseskoder": ["K7PM2QXR9A", "..."],
  "algoritme": "SHA1",
  "cifre": 6,
  "periode": 30
}

Godkend kode

POST /api/v1/kode-godkend.php

Felter ind

Felter ud (HTTP 200)

En kode kan kun bruges én gang. Det gælder både koder fra appen og gendannelseskoder. Et ukendt ekstern_id giver samme svar som en forkert kode: godkendt: false.

Eksempel

POST /api/v1/kode-godkend.php
Authorization: Bearer isk_Ab12Cd34_...
Content-Type: application/json

{"ekstern_id": "bruger-4711", "kode": "287082"}
HTTP 200
{"ok": true, "godkendt": true, "metode": "totp"}
HTTP 200
{"ok": true, "godkendt": true, "metode": "gendannelse", "resterende_gendannelseskoder": 9}
HTTP 200
{"ok": true, "godkendt": false}

Godkendelse på telefonen

I stedet for at taste en kode kan brugeren godkende med et tryk på sin telefon. Det kræver to ting: at I har valgt kun push eller begge under Login-metode i portalen, og at brugeren har koblet sin telefon på. Telefonen kobles på med et link, I laver i portalen under Slutbrugere.

Forløbet er:

  1. Jeres system kalder push-start og får en reference og et tal tilbage.
  2. I viser tal på jeres egen skærm — og kun dét tal.
  3. Brugerens telefon får en besked. Åbner hun den, ser hun tre tal og vælger ét.
  4. Jeres system spørger push-status med referencen, til svaret ikke længere er venter.

Tallet på skærmen er ikke pynt. Uden det kan en fremmed starte et login og håbe, at brugeren trykker ja ved et uheld. Vælger telefonen et forkert tal, bliver godkendelsen afvist med det samme og kan ikke prøves om.

Beskeden til telefonen sendes tom. Hverken Google eller Apple får at vide, hvem der logger ind, eller hvor.

Beskeden skal gennem den push-tjeneste, der hører til brugerens egen browser — Google, Apple eller Mozilla — og de tjenester ligger i USA. Tjenesten kan se den adresse, browseren har givet telefonen, og hvornår der blev sendt til den; den kan ikke se indholdet, for der er intet. Hvilken af de tre det bliver, bestemmer brugeren selv med sit valg af browser. Skriv det i jeres egen oplysning til medarbejderne, når I slår godkendelse på telefonen til.

Start en godkendelse

POST /api/v1/push-start.php

Felter ind

Felter ud (HTTP 201)

Beskeden sendes til alle de telefoner, brugeren har koblet på. Den første, der svarer, afgør sagen.

Eksempel

POST /api/v1/push-start.php
Authorization: Bearer isk_Ab12Cd34_...
Content-Type: application/json

{"ekstern_id": "bruger-4711"}
HTTP 201
{"ok": true, "reference": "9f2c…", "tal": 47, "udloeber_om": 120}

Spørg om svaret

POST /api/v1/push-status.php

Felter ind

Felter ud (HTTP 200)

Luk kun brugeren ind ved godkendt. afvist betyder enten, at brugeren selv sagde nej, eller at telefonen valgte et forkert tal — og I skal behandle de to ens. udloebet betyder, at ingen nåede at svare.

Spørg højst hvert andet sekund. Kaldet tæller ikke på jeres regning, men ét login giver op mod tres forespørgsler.

Eksempel

POST /api/v1/push-status.php
Authorization: Bearer isk_Ab12Cd34_...
Content-Type: application/json

{"reference": "9f2c…"}
HTTP 200
{"ok": true, "status": "venter", "sekunder_tilbage": 83}
HTTP 200
{"ok": true, "status": "godkendt", "sekunder_tilbage": 0}

Slet slutbruger

POST /api/v1/bruger-slet.php

Felter ind

Felter ud (HTTP 200)

Sletningen er endelig. Hemmeligheden og gendannelseskoderne slettes med det samme.

Eksempel

POST /api/v1/bruger-slet.php
Authorization: Bearer isk_Ab12Cd34_...
Content-Type: application/json

{"ekstern_id": "bruger-4711"}
HTTP 200
{"ok": true, "slettet": true}

Fejlkoder

Ved fejl er svaret {"ok": false, "fejl": "<kode>", "besked": "<tekst>"}.

Læs altid fejl i jeres eget system. Det er en fast kode, og den skifter ikke. besked er en forklaring til et menneske, og den står på jeres kontos sprog — det sprog, en ejer har valgt i portalen. De tre svar, der kommer, før nøglen er slået op — metode_ikke_tilladt, noegle_mangler og noegle_ugyldig — står altid på dansk, for der er endnu ingen konto at spørge.

HTTPFejlkodeBetydningKald
400ugyldig_forespoergselKroppen er ikke et JSON-objekt, eller et påkrævet felt mangler eller er ugyldigt.Alle
401noegle_manglerHeaderen Authorization: Bearer mangler.Alle
401noegle_ugyldigNøglen er ukendt eller tilbagekaldt. Lav en ny nøgle i portalen.Alle
403kunde_spaerretJeres konto er ikke aktiv.Alle
403erhvervsbevis_manglerKontoen ligger uden for EU og faktureres uden moms. Vi skal først have set dokumentationen for, at I er en virksomhed. Skriv jeres hjemmeside ind under Virksomheden i portalen, eller vedhæft en kontrakt, en ordrebekræftelse eller en registreringsattest samme sted. Nøglerne virker, så snart vi har set den — normalt inden for en hverdag.Alle
403push_ikke_slaaet_tilJeres konto står på kun kode. Skift til kun push eller begge under Login-metode i portalen.push-start
404bruger_findes_ikkeDer findes ingen slutbruger med det ekstern_id hos jer.bruger-slet, push-start
404ukendt_referenceReferencen findes ikke hos jer. Den kan også være ryddet, fordi der er gået mere end en uge.push-status
405metode_ikke_tilladtKaldet brugte ikke POST.Alle
409bruger_findesDer findes allerede en slutbruger med det ekstern_id hos jer.bruger-opret
409ingen_enhedSlutbrugeren har ingen telefon koblet på. Lav et tilkoblingslink i portalen under Slutbrugere.push-start
429noegle_spaerretNøglen holder pause efter for mange forkerte forsøg. Den virker igen af sig selv. Svaret har feltet proev_igen_om med antal sekunder, og det samme tal står i headeren Retry-After.Alle
429slutbruger_spaerretSlutbrugeren er midlertidigt spærret efter for mange forkerte forsøg. Gælder også, selvom koden er rigtig.kode-godkend
500intern_fejlUventet fejl hos ISIRO.Alle
502besked_kunne_ikke_sendesIngen af brugerens telefoner tog imod beskeden. Bed brugeren koble telefonen på igen, eller lad brugeren taste en kode i stedet.push-start

Grænser

En spærret slutbruger kan låses op i portalen under Slutbrugere.

Pausen på en nøgle går over af sig selv, og nøglen skal ikke laves om. Svaret siger i proev_igen_om og i headeren Retry-After, hvor mange sekunder der er tilbage. Hold derfor noegle_spaerret og noegle_ugyldig adskilt i jeres eget system: det første skal vente og prøve igen, det andet kræver en ny nøgle.

Anbefalinger

  1. Vis QR-koden med det samme. Vis otpauth_uri som QR-kode for brugeren i samme forløb, som du opretter brugeren i. Bed brugeren taste den første kode, så brugeren bliver bekræftet.
  2. Få brugeren til at gemme sine 10 gendannelseskoder. De er brugerens eneste vej ind, hvis telefonen bliver væk, og de vises kun én gang.
  3. Gem aldrig selv hemmeligheden. ISIRO gemmer den krypteret. Dit system behøver kun ekstern_id. Smid hemmeligheden og gendannelseskoderne væk, så snart brugeren har set dem.
  4. Behold kodefeltet, når I bruger push. En kode fra appen virker uden net og uden dækning. Push gør ikke, og leveringen er «så godt som muligt», ikke garanteret. Vælger I kun push, kan en bruger med en død telefon ikke komme ind.
  5. Fortæl brugeren to ting, når telefonen kobles på. At hun skal vælge det tal, der står på skærmen — ikke bare trykke ja. Og at hun på iPhone skal lægge siden på hjemmeskærmen, før beskeder kan sendes; det er Apples regel og ikke noget, ISIRO kan ændre.