HonkIO Auth

How it works

HonkIO Auth is a hosted sign-in page and user directory. Your app sends people to the sign-in page on a hostname you own, such as login.acme.ca. They sign in with an email code or link, a text-message code, or a passkey: there are no passwords and no social logins. HonkIO then sends them back to your app, signed in.

The sign-in page is a standard OpenID Connect provider: authorization code with PKCE, ID tokens, userinfo, JWKS, discovery and RP-initiated logout. Use any OIDC library; the quickstarts show Next.js, Express, FastAPI, Django and Laravel.

HonkIO keeps the full user directory for each app: users, profiles, sessions and sign-in history, and on Business, organizations with roles and invitations. Manage it in the dashboard or through the management API, and get webhooks when it changes. It’s on the same HonkIO account and the same prepaid CAD balance as your texts and email.

What you need

Before the first sign-in, you need:

• A HonkIO account and an API key with the auth_apps permission (API keys). Existing keys don’t gain the HonkIO Auth permissions: create a key or edit one.
• A domain you control, and access to its DNS. Every app, test apps included, runs on its own subdomain: there is no shared HonkIO sign-in domain. See Domain setup.
• The address of your app’s callback route, such as https://app.acme.ca/auth/callback, to register as a redirect URI.

Then:

1. Create an app with POST /v1/auth-apps, or in the dashboard’s Auth section. Keep the client secret: it’s shown once.
2. Publish the TXT and CNAME records the response lists, then verify the domain. HonkIO gets the HTTPS certificate once the records check out.
3. Point your OIDC library at the app’s issuer (https:// and your hostname) with the client ID and secret. The quickstarts show the rest.

curl -X POST https://api.honkio.ca/v1/auth-apps \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "login-dev.acme.ca",
    "name": "Acme",
    "redirect_uris": ["http://localhost:3000/auth/callback"],
    "post_logout_redirect_uris": ["http://localhost:3000/"]
  }'
# The response holds client_id, client_secret (shown once) and dns_records.

Test and live apps

Apps follow HonkIO’s test and live split: a test API key creates and manages test apps, a live key live apps. Test apps send nothing real, no emails and no texts. They’re free, unlimited in number, get every paid feature, and are capped at 100 users.

On a test app, the fixed code 000000 works only for reserved test identifiers (see Sign-in methods). Real addresses and numbers can sign in to a test app only with a passkey. Test sign-in pages show a Test mode banner that can’t be hidden.

A test app has its own hostname (for example login-dev.acme.ca), issuer and signing keys, so a token from a test app is never accepted by a live one. http://localhost redirect URIs are allowed on test apps only.

Leaving HonkIO

Export all of an app’s users, organizations and roles as a file at any time (Export). Because the issuer is your own hostname, you can later run sign-in elsewhere on that same hostname. Passkeys can’t be exported, by design. By default they’re tied to your whole domain, so users can keep them if your next provider runs sign-in on that domain; otherwise they add them again.