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 your Audiobookshelf server address on the login screen. Use the protocol picker to toggle between HTTPS (default) and HTTP, then enter the hostname, port (if applicable), 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

The protocol picker keeps the scheme and URL field in sync — switching from HTTPS to HTTP updates the URL automatically, so you don't need to type the protocol manually.

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.

Auth Mode Picker

The login screen includes an auth mode picker with three options: Username/Password, API Key, and OIDC (SSO). Pick the one that matches how your server is configured. The form updates to show only the fields relevant to your choice.

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.

API Key

If you'd rather not expose a password in a client, choose API Key in the auth mode picker. Generate a key in your Audiobookshelf server settings, paste it into FableFrog, and sign in. FableFrog validates the token on each refresh so revoked keys are detected immediately and you'll be prompted to sign in again.

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.

Redirect URI Configuration

FableFrog uses the custom URL scheme fablefrog://oauth to receive the authorization code after you authenticate with your identity provider. This URI must be registered in two places for the OIDC flow to work:

1. Audiobookshelf Server

In your Audiobookshelf authentication settings, add fablefrog://oauth to the Mobile Redirect URIs field. The default value is audiobookshelf://oauth (for the official Audiobookshelf app). Add fablefrog://oauth alongside it, separated by a comma:

audiobookshelf://oauth, fablefrog://oauth

You can configure this in FableFrog via Settings > Server Administration > Authentication, or through the Audiobookshelf web UI.

2. Your Identity Provider

Add fablefrog://oauth as a valid redirect URI in your identity provider's client configuration. This is required for all OIDC providers — without it, the provider will reject the redirect back to FableFrog after authentication.

If your provider supports RP-Initiated Logout, also add fablefrog://logout as a valid post-logout redirect URI.

Provider-specific examples:

  • Keycloak: In your client settings, add fablefrog://oauth and fablefrog://logout to the Valid Redirect URIs field.
  • Google: In the Google Cloud Console under your OAuth 2.0 client credentials, add fablefrog://oauth as an Authorized redirect URI.
  • Authelia / Authentik: Add fablefrog://oauth to your client's allowed redirect URIs. Consult your provider's documentation for the exact field name.

Troubleshooting Redirects

If the OIDC redirect fails or gets stuck:

  • Missing redirect URI. The most common cause is that fablefrog://oauth hasn't been added to both your Audiobookshelf Mobile Redirect URIs and your identity provider's client configuration. See Redirect URI Configuration above.
  • Provider reachability. Your identity provider must be reachable from your iPhone, not just from the server's network.
  • Mixed content. If your Audiobookshelf server uses HTTPS but your identity provider uses HTTP (or vice versa), the browser may block the redirect. Use HTTPS for both.

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. Use the inline library switcher in the Home toolbar for a one-tap switch, or go to Settings and tap your current library name to see the full list. Switching libraries refreshes all browse tabs, history, the mini player, and stats to scope everything to 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 →