Signing in

Apogee signs in to a BookOrbit server that you host, or have an account on. You need:

1. The server address, like https://books.example.com, http://192.168.1.10:8080, or a Tailscale address like http://my-nas.tail1234.ts.net:8080
2. Your username and password for that server, or an account on your server’s SSO provider

Two addresses for one server

Since build 244 your server can have two addresses: the public one that works anywhere, and an optional one on your own network. Apogee tries both and uses whichever answers, so you don’t edit a URL when you walk out the door. Add the second one under Settings, then Connection.

Sign in for the first time on the public address, away from home or on mobile data. Many home routers can’t route a public address back inside their own network, so a first sign-in over the home Wi-Fi can fail on a setup that’s otherwise fine. Add the home address afterwards.

SSO, passkeys and magic links

If your server signs you in through an identity provider such as Authelia, Authentik, Keycloak or Pocket ID, tap Sign in with SSO. Apogee opens your server’s own sign-in page and adopts the session it creates, so whatever your server is set up for works the same way in the app.

Two things SSO needs:

• HTTPS. Provider sign-in fails on a plain http:// address. This is a limit of the server’s sign-in page, not of Apogee, and it fails the same way in a browser.
• The server’s main address. SSO only completes on the address your server is configured with. If you’ve added a second, home-network address, sign in on the main one.

What works, method by method

• Passwords work everywhere: the app’s own form, or the server page behind Sign in with SSO.
• Self-hosted providers (Authelia, Authentik, Keycloak, Pocket ID) work in the SSO sheet.
• Google and Microsoft refuse to sign in inside any app’s embedded page, so they don’t work yet.
• Passkeys don’t work in the app. iOS shows passkey prompts only in a real browser, never inside an app’s embedded sign-in page. The passkey button on your provider’s page will do nothing, and some providers then claim you cancelled. You didn’t. If your provider also accepts a password, type it instead.

Pocket ID: sign in with a login code

Pocket ID only uses passkeys, so it needs one extra step. Pocket ID has a built-in fallback for devices that can’t show a passkey prompt, and it works in Apogee:

1. In the Pocket ID admin panel, open Users, then the ⋯ menu on your user, then Login Code. Keep the default one-hour expiry. Don’t pick an expiry under 15 minutes: that makes a short code the sign-in page won’t accept.
2. In Apogee, tap Sign in with SSO, then your provider’s button as usual.
3. On the Pocket ID page, tap alternative sign-in, then Login code, and type the code.

The sign-in finishes on its own from there. Codes are single-use, so a failed attempt needs a fresh one. Once you’re in, you stay signed in as long as you open the app about once a week on default server settings; you only need a new code after signing out or a long break.

Two Pocket ID settings worth knowing: enabling email one-time access lets you request a code by email instead of the admin panel, and the requires reauthentication option on the BookOrbit client must stay off, or codes stop being accepted for sign-in.

Magic links

Since build 258 you can paste a magic link on the sign-in screen: copy the whole link, then tap Paste next to Have a magic link?. The link fills in the server address on its own. Your server only issues magic links for shared accounts, so this is for an account your household shares, not a replacement for your main account.

Common sign-in failures, and fixes

Use the server address, not a link to a feed

Enter the address of the server itself, like https://books.example.com. Don’t paste a link that ends in a path, such as an OPDS feed link.

On builds before 252 an address with a path signed in and loaded your library, then failed on every download, every cover and all audiobook streaming. Build 252 and later cut a saved address back to the server on their own, so an address you stored months ago is corrected without signing in again.

“It works in Safari but not in Apogee”: the wrong scheme

The most common self-hosting mistake is typing https:// for a server that only speaks plain HTTP on that port. That’s typical for local and Tailscale setups with no reverse proxy in front of them. If your server has no certificate, use http:// with the right port.

Local servers: check the Local Network permission

iOS controls which apps can reach devices on your own network. If your server is local, or reached over a local route, and sign-in fails instantly:

Settings → Apogee → Local Network. Make sure it’s on.

Tailscale

Tailscale addresses work: .ts.net names, and addresses starting 100.. Two things to watch:

• Use http:// unless you’ve set up Tailscale HTTPS certificates for that machine.
• The device running Apogee has to be signed in to the same tailnet, with the Tailscale app running.

.lan and other local-only names

iOS trusts only certain names as local. If your server uses a name like http://nas.lan:8080 and sign-in fails, try the server’s IP address or its .local name instead.

Cloudflare Access in front of your server

If your BookOrbit server sits behind Cloudflare Access, an app can’t do the browser sign-in. Apogee supports service tokens instead. Create one in the Cloudflare Zero Trust dashboard, under Access → Service Auth → Service Tokens, then enter the Client ID and Client Secret when you add the server in Apogee.

You can correct an Access token later without signing out. It lives under Settings, then Connection, then Headers and tokens.

Still failing?

• Load the address in Safari on the same device, on the same network, and check it works there first.
• Hotel and café Wi-Fi with a sign-in page can make a dead server look reachable. Try it on mobile data or your home Wi-Fi.
• If you’re still stuck, please post in Q&A with your setup: your server version, the shape of your address (no need to share the real one), and the exact error you see.