Connecting to Your Server

Configure your Audiobookshelf server connection in FableFrog, including OIDC/SSO, reverse proxies, and multi-library support.

Basic Connection

FableFrog connects directly to your Audiobookshelf server. No intermediary services, no cloud relay. Your device talks to your server and nothing else.

Server URL Format

Enter the full URL of your Audiobookshelf instance on the login screen. The URL must include the protocol and, if applicable, the port and path:

  • Standard HTTPS: https://abs.example.com
  • Custom port: https://abs.example.com:13378
  • Path prefix (reverse proxy): https://example.com/audiobookshelf
  • Local network (HTTP): http://192.168.1.100:13378

If your server uses HTTPS (recommended), FableFrog enforces TLS with no App Transport Security exceptions. If you need to connect over plain HTTP (for example, on a local network), this works but is not recommended for connections over the internet.

Username and Password

Enter your Audiobookshelf credentials and tap Sign In. FableFrog stores your credentials securely in the iOS Keychain, never in files or UserDefaults.

Remember This Server

When you sign in successfully, FableFrog remembers the server URL for future logins. The next time you open the login screen, your server address will be pre-filled.

Server Validation

Before completing the login flow, FableFrog validates the connection by pinging your server's status endpoint. If the server is unreachable, returns an unexpected response, or is running an incompatible version, you'll see a specific error message explaining the problem.

OIDC / Single Sign-On

FableFrog supports OpenID Connect (OIDC) for single sign-on authentication, letting you use your existing identity provider instead of a local Audiobookshelf password.

Supported Providers

Any OIDC-compliant identity provider works with FableFrog. Your OIDC provider must be configured on your Audiobookshelf server first. FableFrog discovers the available providers from the server automatically.

How the OAuth Flow Works

When you tap an OIDC provider button on the login screen, FableFrog opens an in-app browser to your identity provider's login page. After you authenticate, the provider redirects back to FableFrog with an authorization code, which is exchanged for access and refresh tokens. The entire flow happens between your device, your identity provider, and your Audiobookshelf server.

Troubleshooting Redirects

If the OIDC redirect fails or gets stuck, check the following:

  • Ensure the redirect URI configured in your identity provider matches what Audiobookshelf expects.
  • Verify that your identity provider is reachable from your iPhone (not just from the server's network).
  • Check for CORS or mixed-content issues if your identity provider and Audiobookshelf server are on different domains or protocols.

Reverse Proxy Setups

Many self-hosters run Audiobookshelf behind a reverse proxy. FableFrog accommodates this with custom HTTP header support.

Custom HTTP Headers

In the login screen, you can add custom HTTP headers that FableFrog sends with every request to your server. This is useful for:

  • Authentication headers required by your proxy (e.g., X-Forwarded-User, Remote-User)
  • API keys or tokens your proxy layer expects
  • Custom routing headers for multi-service setups

Common Setups

Caddy: typically the simplest configuration. Caddy handles TLS automatically, and FableFrog connects to your Caddy address with no special headers needed unless you've added an authentication layer.

Nginx: ensure your Nginx config passes WebSocket connections correctly (proxy_set_header Upgrade $http_upgrade) since FableFrog uses Socket.io for real-time sync. If you use proxy_pass with a path prefix, include that path in your server URL.

Traefik: works well out of the box with standard Traefik labels. If you use Traefik's ForwardAuth middleware, configure the required authentication headers in FableFrog.

Multiple Libraries

Audiobookshelf supports multiple libraries on a single server, and FableFrog handles this seamlessly.

Library Selection on Login

If your server has more than one audiobook library, FableFrog prompts you to choose one after authentication. Only audiobook libraries are shown; podcast libraries are not currently supported.

Switching Libraries

You can switch between libraries at any time without signing out. Go to Settings and tap your current library name to see the full list. Switching libraries refreshes the Home screen and browse views with content from the selected library.

Troubleshooting Connection Issues

Common Errors

  • "Unable to connect to server": FableFrog cannot reach the URL you entered. Verify the address is correct, the server is running, and your device is on the same network (or the server is exposed to the internet).
  • "Invalid credentials": double-check your username and password. Audiobookshelf credentials are case-sensitive.
  • "Server version not supported": FableFrog requires Audiobookshelf v2.x. Update your server if you're running an older version.

Server Version Compatibility

FableFrog is tested against Audiobookshelf v2.x releases. If you're running a development or pre-release build of Audiobookshelf, some features may behave unexpectedly. Stick to stable releases for the best experience.

HTTPS and App Transport Security

iOS enforces App Transport Security (ATS) by default, which requires HTTPS connections. FableFrog does not add ATS exceptions, so plain HTTP connections may be blocked on some network configurations. Using HTTPS with a valid certificate (e.g., via Let's Encrypt) is strongly recommended and avoids these issues entirely.

If you need HTTP access on a local network, it generally works for local/private IP addresses, but HTTPS remains the more reliable option.

Found a typo or error? Let us know
Previous← Getting StartedNextLibrary & Browsing →