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
ekstern_id– required. Your own id for the user, at most 191 characters. Prefer an id without personal data over an email address.kontonavn– optional. The name shown in the authenticator app. If left out,ekstern_idis used.udsteder– optional. The issuer name in the app. If left out, your customer name is used.
Fields out (HTTP 201)
ok–trueslutbruger_id– theekstern_idyou senthemmelighed– the TOTP secret in base32. Returned this one time only.otpauth_uri– the address to show as a QR codegendannelseskoder– a list of 10 recovery codes. Returned this one time only.algoritme(SHA1),cifre(6),periode(30seconds)
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
ekstern_id– requiredkode– required. Either the 6-digit code from the app or one of the 10-character recovery codes. Spaces and hyphens are ignored, and upper and lower case are equally good.
Fields out (HTTP 200)
ok–truegodkendt–trueorfalsemetode–totporgendannelse. Only when the code was accepted.resterende_gendannelseskoder– the number of unused recovery codes. Only when the method isgendannelse.
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:
- Your system calls
push-startand gets back areferenceand atal. - You show
talon your own screen — and only that number. - The user's phone receives a message. When she opens it, she sees three numbers and picks one.
- Your system asks
push-statuswith the reference until the answer is no longerventer.
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
ekstern_id– required
Fields out (HTTP 201)
ok–truereference– 64 characters. It is used to ask for the answer. Keep it until the approval is settled, and never show it to the user.tal– the number between 10 and 99 that you must show on the screenudloeber_om– seconds the approval lives. Today 120.
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
reference– required. The one you got frompush-start.
Fields out (HTTP 200)
ok–truestatus–venter,godkendt,afvistorudloebetsekunder_tilbage– seconds left. 0 when the status is notventer.
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
ekstern_id– required
Fields out (HTTP 200)
ok–trueslettet–true
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.
| HTTP | Error code | Meaning | Call |
|---|---|---|---|
| 400 | ugyldig_forespoergsel | The body is not a JSON object, or a required field is missing or invalid. | All |
| 401 | noegle_mangler | The Authorization: Bearer header is missing. | All |
| 401 | noegle_ugyldig | The key is unknown or revoked. Create a new key in the portal. | All |
| 403 | kunde_spaerret | Your account is not active. | All |
| 403 | erhvervsbevis_mangler | The 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 |
| 403 | push_ikke_slaaet_til | Your account is set to code only. Switch to push only or both under Sign-in method in the portal. | push-start |
| 404 | bruger_findes_ikke | There is no end user with that ekstern_id at your account. | bruger-slet, push-start |
| 404 | ukendt_reference | The reference does not exist at your account. It may also have been cleared because more than a week has passed. | push-status |
| 405 | metode_ikke_tilladt | The call did not use POST. | All |
| 409 | bruger_findes | There is already an end user with that ekstern_id at your account. | bruger-opret |
| 409 | ingen_enhed | The end user has no phone connected. Create a connection link in the portal under End users. | push-start |
| 429 | noegle_spaerret | The 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 |
| 429 | slutbruger_spaerret | The end user is temporarily blocked after too many wrong attempts. This applies even when the code is correct. | kode-godkend |
| 500 | intern_fejl | Unexpected error at ISIRO. | All |
| 502 | besked_kunne_ikke_sendes | None 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
- Per end user: after 5 wrong attempts the end user is blocked. The block lasts 1 minute the first time and thereafter 5, 15 and 60 minutes at every fifth new failure. A correct code resets the count. An attempt to reuse a code counts as a wrong attempt.
- Per key: 200 wrong attempts within 10 minutes pause the key for 15 minutes. While that lasts, every call with the key is refused with
noegle_spaerretand HTTP 429. Attempts with an unknownekstern_idcount towards this too.
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
- Show the QR code straight away. Show
otpauth_urias 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. - 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.
- 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. - 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.
- 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.