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
ekstern_id– påkrævet. Dit eget id for brugeren, højst 191 tegn. Brug gerne et id uden personoplysninger frem for en e-mailadresse.kontonavn– valgfrit. Navnet der vises i autentificeringsappen. Udelades det, brugesekstern_id.udsteder– valgfrit. Udstedernavnet i appen. Udelades det, bruges jeres kundenavn.
Felter ud (HTTP 201)
ok–trueslutbruger_id– detekstern_iddu sendtehemmelighed– TOTP-hemmeligheden i base32. Returneres kun denne ene gang.otpauth_uri– adressen der skal vises som QR-kodegendannelseskoder– liste med 10 gendannelseskoder. Returneres kun denne ene gang.algoritme(SHA1),cifre(6),periode(30sekunder)
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
ekstern_id– påkrævetkode– påkrævet. Enten den 6-cifrede kode fra appen eller en af de 10 tegn lange gendannelseskoder. Mellemrum og bindestreger ignoreres, og store og små bogstaver er lige gode.
Felter ud (HTTP 200)
ok–truegodkendt–trueellerfalsemetode–totpellergendannelse. Kun når koden er godkendt.resterende_gendannelseskoder– antal ubrugte gendannelseskoder. Kun når metoden ergendannelse.
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:
- Jeres system kalder
push-startog får enreferenceog ettaltilbage. - I viser
talpå jeres egen skærm — og kun dét tal. - Brugerens telefon får en besked. Åbner hun den, ser hun tre tal og vælger ét.
- Jeres system spørger
push-statusmed referencen, til svaret ikke længere erventer.
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
ekstern_id– påkrævet
Felter ud (HTTP 201)
ok–truereference– 64 tegn. Den bruges til at spørge om svaret. Gem den, til godkendelsen er afgjort, og vis den aldrig for brugeren.tal– tallet mellem 10 og 99, som I skal vise på skærmenudloeber_om– sekunder, godkendelsen lever. I dag 120.
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
reference– påkrævet. Den, I fik frapush-start.
Felter ud (HTTP 200)
ok–truestatus–venter,godkendt,afvistellerudloebetsekunder_tilbage– antal sekunder tilbage. 0, når status ikke erventer.
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
ekstern_id– påkrævet
Felter ud (HTTP 200)
ok–trueslettet–true
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.
| HTTP | Fejlkode | Betydning | Kald |
|---|---|---|---|
| 400 | ugyldig_forespoergsel | Kroppen er ikke et JSON-objekt, eller et påkrævet felt mangler eller er ugyldigt. | Alle |
| 401 | noegle_mangler | Headeren Authorization: Bearer mangler. | Alle |
| 401 | noegle_ugyldig | Nøglen er ukendt eller tilbagekaldt. Lav en ny nøgle i portalen. | Alle |
| 403 | kunde_spaerret | Jeres konto er ikke aktiv. | Alle |
| 403 | erhvervsbevis_mangler | Kontoen 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 |
| 403 | push_ikke_slaaet_til | Jeres konto står på kun kode. Skift til kun push eller begge under Login-metode i portalen. | push-start |
| 404 | bruger_findes_ikke | Der findes ingen slutbruger med det ekstern_id hos jer. | bruger-slet, push-start |
| 404 | ukendt_reference | Referencen findes ikke hos jer. Den kan også være ryddet, fordi der er gået mere end en uge. | push-status |
| 405 | metode_ikke_tilladt | Kaldet brugte ikke POST. | Alle |
| 409 | bruger_findes | Der findes allerede en slutbruger med det ekstern_id hos jer. | bruger-opret |
| 409 | ingen_enhed | Slutbrugeren har ingen telefon koblet på. Lav et tilkoblingslink i portalen under Slutbrugere. | push-start |
| 429 | noegle_spaerret | Nø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 |
| 429 | slutbruger_spaerret | Slutbrugeren er midlertidigt spærret efter for mange forkerte forsøg. Gælder også, selvom koden er rigtig. | kode-godkend |
| 500 | intern_fejl | Uventet fejl hos ISIRO. | Alle |
| 502 | besked_kunne_ikke_sendes | Ingen af brugerens telefoner tog imod beskeden. Bed brugeren koble telefonen på igen, eller lad brugeren taste en kode i stedet. | push-start |
Grænser
- Pr. slutbruger: Efter 5 forkerte forsøg spærres slutbrugeren. Spærringen varer 1 minut første gang og derefter 5, 15 og 60 minutter ved hver femte nye fejl. En rigtig kode nulstiller tællingen. Et forsøg på at genbruge en kode tæller som et forkert forsøg.
- Pr. nøgle: 200 forkerte forsøg inden for 10 minutter sætter nøglen på pause i 15 minutter. Imens afvises alle kald med nøglen med
noegle_spaerretog HTTP 429. Forsøg med et ukendtekstern_idtæller også med.
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
- Vis QR-koden med det samme. Vis
otpauth_urisom 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. - 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.
- 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. - 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.
- 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.