Skip to content

Quickstart: the API

This continues the Quickstart. You have ianua running and the hello test app is started. Everything the dashboard does goes through this same API, so anything you can click you can also script.

Sign in to the API and keep the session token:

Terminal window
API=https://api.ianua.localhost/api/v1
TOKEN=$(curl -sk -X POST $API/login \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"Violet otters juggle 42 brass lanterns at dusk"}' | jq -r .refresh_token)
T=$API/organizations/acme/tenants/main
auth=(-sk -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json')

T is your tenant: organization acme, tenant main. Every call below goes to it.

A sign-in from a device ianua has not seen, by someone with no second factor, waits for a confirmation by email: the answer has "email_confirmation_required": true, and the token works only once you confirm. Send the token from the mailed link with the waiting sign-in’s token:

Terminal window
curl -sk -X POST $API/login/confirm \
-H 'Content-Type: application/json' \
-d "{\"token\":\"<token from the link>\",\"refresh_token\":\"$TOKEN\"}"

If your address has an account in more than one organization, the answer has "status": "choose_organization" and a list of them instead of a token. Sign in again with "organization": "acme" added to the body.

Create a pipeline and switch it on. A new pipeline always contains the two checks that can never be removed: who is calling and are they allowed.

Terminal window
PIPELINE=$(curl "${auth[@]}" -X POST $T/pipelines -d '{"name":"Default"}' | jq -r .id)
curl "${auth[@]}" -X POST $T/pipelines/$PIPELINE/activate

Tell ianua where the app lives:

Terminal window
SERVICE=$(curl "${auth[@]}" -X POST $T/services -d '{
"name": "hello",
"upstream": {
"url": "http://hello:80",
"timeout_secs": 30,
"preserve_host": false,
"expected_audience": {"pinned": "hello"},
"identity": "token"
}
}' | jq -r .id)

expected_audience says which tokens the service accepts: {"pinned": "hello"} takes only tokens made for hello, and "no_token_accepted" takes none. Any route that is not public refuses to save on a service with no pinned audience. identity is "token", or "client_certificate" for a service only callers with a client certificate may reach.

Everything under /public/ is open to anyone. Everything under /private/ needs a signed-in caller.

Terminal window
curl "${auth[@]}" -X POST $T/routes -d "{
\"name\": \"public\", \"path_pattern\": \"/public/*\", \"methods\": [\"Get\"],
\"service_id\": \"$SERVICE\", \"pipeline_id\": \"$PIPELINE\", \"policy\": \"Public\"
}"
curl "${auth[@]}" -X POST $T/routes -d "{
\"name\": \"private\", \"path_pattern\": \"/private/*\", \"methods\": [\"Get\"],
\"service_id\": \"$SERVICE\", \"pipeline_id\": \"$PIPELINE\", \"policy\": \"Authenticated\"
}"

Each call answers with the new route’s id.

Your tenant’s apps are served at acme-main.apps.localhost: the organization, a dash, the tenant, then your apps domain. The gateway picks up each change within a moment, so there is nothing to restart.

A public request goes through. This one also tries to claim to be someone else, by setting identity headers itself:

Terminal window
curl -sk https://acme-main.apps.localhost/public/hello \
-H "X-Forwarded-User: admin" \
-H "X-Ianua-Assertion: forged"

The app answers with what it received:

Host: hello:80
User-Agent: curl/8.7.1
Accept: */*
X-Forwarded-For: …
X-Forwarded-Host: acme-main.apps.localhost
X-Forwarded-Proto: https

The request arrived, but neither of the headers you sent is there. The gateway removes identity headers a caller sets, because only the gateway may say who a caller is.

A private request without a login is refused:

Terminal window
curl -sk https://acme-main.apps.localhost/private/hello
{"correlation_id":"…","error":"denied: missing bearer token"}

The status is 401, and the app never saw the request.

A path no route covers is refused too:

Terminal window
curl -sk -o /dev/null -w "%{http_code}\n" https://acme-main.apps.localhost/admin

That prints 404. Nothing reaches an app unless a route says it may.

Every one of these decisions, allowed or refused, is recorded. The gateway writes one line per request, with the decision and the reason for it:

Terminal window
docker compose logs zero | grep path=/private/hello
WARN … request denied … method=GET path=/private/hello … decision="denied" deny_status=401 deny_reason=denied: missing bearer token

The same records feed the traffic figures on your tenant’s overview in the dashboard.

And the gateway will not be pointed at the wrong place. Try to make the cloud metadata service, where cloud servers keep their credentials, the address of a service:

Terminal window
curl "${auth[@]}" -X POST $T/services -d '{
"name": "sneaky",
"upstream": {
"url": "http://169.254.169.254/",
"timeout_secs": 30,
"preserve_host": false,
"expected_audience": "no_token_accepted",
"identity": "token"
}
}'

It is refused with status 422, whatever networks you allow:

{"error":"domain_error","message":"Upstreams may not target an internal address outside the networks this deployment allows."}

Clean up

Terminal window
docker rm -f hello
docker compose down # stop, keeping your data
docker compose down -v # stop and delete all data

What’s next

  • How it works explains what happened to each of those requests, stage by stage.
  • Install on Kubernetes sets ianua up for real use with two Helm commands: one for ianua, one for the dashboard.
  • To let people sign in to a private route, connect your app to ianua over OpenID Connect. The OAuth page under Domain contexts explains how an app is registered and signs people in.