ISIRO
May we measure whether our ads work?

ISIRO uses Google Ads and would like to know whether an ad turns into a customer. That needs a cookie which is not necessary for the site to work — so we ask before we do it.

If you say no, nothing happens. We remember your no in your browser so you are not asked again, and that is the only thing we store. You can change your mind at any time at the bottom of the page.

Read more in the cookie policy

Documentation

ISIRO has five calls. Every address below is relative to ISIRO's address.

Authenticating with an API key

Every call must send the API key in the header:

Authorization: Bearer <your API key>

You create keys in the portal under API keys. The full key is shown only once, when it is created. ISIRO stores only a hash of the key and therefore cannot show it again. If you lose it, create a new one and revoke the old one.

Every call must use POST, and the body must be a JSON object with Content-Type: application/json. The answer is always JSON.

Create end user

POST /api/v1/bruger-opret.php

Fields in

Fields out (HTTP 201)

The user is not confirmed until the first correct code has been accepted.

Example

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
}

Verify code

POST /api/v1/kode-godkend.php

Fields in

Fields out (HTTP 200)

A code can only be used once. That applies both to codes from the app and to recovery codes. An unknown ekstern_id gives the same answer as a wrong code: godkendt: false.

Example

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}

Approval on the phone

Instead of typing a code, the user can approve with one tap on their phone. That takes two things: that you have chosen push only or both under Sign-in method in the portal, and that the user has connected their phone. The phone is connected with a link you create in the portal under End users.

The flow is:

  1. Your system calls push-start and gets back a reference and a tal.
  2. You show tal on your own screen — and only that number.
  3. The user's phone receives a message. When she opens it, she sees three numbers and picks one.
  4. Your system asks push-status with the reference until the answer is no longer venter.

The number on the screen is not decoration. Without it a stranger can start a sign-in and hope the user taps yes by accident. If the phone picks a wrong number, the approval is denied at once and cannot be tried again.

The message to the phone is sent empty. Neither Google nor Apple is told who is signing in, or where.

The message has to go through the push service belonging to the user's own browser — Google, Apple or Mozilla — and those services are in the United States. The service can see the address the browser gave the phone, and when something was sent to it; it cannot see the content, because there is none. Which of the three it will be is decided by the user's own choice of browser. Write that into your own notice to your staff when you switch approval on the phone on.

Start an approval

POST /api/v1/push-start.php

Fields in

Fields out (HTTP 201)

The message is sent to every phone the user has connected. The first one to answer settles it.

Example

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}

Ask for the answer

POST /api/v1/push-status.php

Fields in

Fields out (HTTP 200)

Only let the user in on godkendt. afvist means either that the user said no herself, or that the phone picked a wrong number — and you must treat the two the same. udloebet means nobody answered in time.

Ask at most every two seconds. The call does not count towards your invoice, but one sign-in gives up to sixty requests.

Example

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}

Delete end user

POST /api/v1/bruger-slet.php

Fields in

Fields out (HTTP 200)

The deletion is final. The secret and the recovery codes are deleted at the same moment.

Example

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

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

Error codes

On an error the answer is {"ok": false, "fejl": "<code>", "besked": "<text>"}.

Always read fejl in your own system. It is a fixed code and it does not change. besked is an explanation for a human being, and it is written in your account's language — the language an owner has chosen in the portal. The three answers that come before the key has been looked up — metode_ikke_tilladt, noegle_mangler and noegle_ugyldig — are always in Danish, because there is no account to ask yet.

HTTPError codeMeaningCall
400ugyldig_forespoergselThe body is not a JSON object, or a required field is missing or invalid.All
401noegle_manglerThe Authorization: Bearer header is missing.All
401noegle_ugyldigThe key is unknown or revoked. Create a new key in the portal.All
403kunde_spaerretYour account is not active.All
403erhvervsbevis_manglerThe account is outside the EU and is invoiced without VAT. We first need to have seen the documentation that you are a business. Enter your website under Company in the portal, or attach a contract, an order confirmation or a certificate of registration in the same place. The keys will work as soon as we have seen it — normally within one working day.All
403push_ikke_slaaet_tilYour account is set to code only. Switch to push only or both under Sign-in method in the portal.push-start
404bruger_findes_ikkeThere is no end user with that ekstern_id at your account.bruger-slet, push-start
404ukendt_referenceThe reference does not exist at your account. It may also have been cleared because more than a week has passed.push-status
405metode_ikke_tilladtThe call did not use POST.All
409bruger_findesThere is already an end user with that ekstern_id at your account.bruger-opret
409ingen_enhedThe end user has no phone connected. Create a connection link in the portal under End users.push-start
429noegle_spaerretThe key is paused after too many wrong attempts. It starts working again on its own. The answer carries the field proev_igen_om with a number of seconds, and the same number is in the Retry-After header.All
429slutbruger_spaerretThe end user is temporarily blocked after too many wrong attempts. This applies even when the code is correct.kode-godkend
500intern_fejlUnexpected error at ISIRO.All
502besked_kunne_ikke_sendesNone of the user's phones accepted the message. Ask the user to connect the phone again, or let the user type a code instead.push-start

Limits

A blocked end user can be unblocked in the portal under End users.

A pause on a key passes on its own, and the key does not have to be replaced. The answer states in proev_igen_om and in the Retry-After header how many seconds are left. Keep noegle_spaerret and noegle_ugyldig apart in your own system: the first one should wait and try again, the second one calls for a new key.

Recommendations

  1. Show the QR code straight away. Show otpauth_uri as a QR code for the user in the same flow in which you create the user. Ask the user to type the first code, so that the user becomes confirmed.
  2. Get the user to save their 10 recovery codes. They are the user's only way in if the phone is lost, and they are shown only once.
  3. Never store the secret yourself. ISIRO stores it encrypted. Your system only needs ekstern_id. Discard the secret and the recovery codes as soon as the user has seen them.
  4. Keep the code field when you use push. A code from the app works without a network and without coverage. Push does not, and delivery is "best effort", not guaranteed. If you choose push only, a user with a dead phone cannot get in.
  5. Tell the user two things when the phone is connected. That she must pick the number shown on the screen — not simply tap yes. And that on an iPhone she must add the page to the home screen before messages can be sent; that is Apple's rule and not something ISIRO can change.