SoundLeaf

SoundLeaf Logo
All Docs Advanced

Cloudflare Access Setup

Connect SoundLeaf to your Audiobookshelf server behind Cloudflare Zero Trust

If you’re running Audiobookshelf behind a Cloudflare Tunnel with Zero Trust protection, you’ll need to configure custom headers in SoundLeaf to authenticate.

Why Custom Headers?

Cloudflare Access adds an authentication layer before your Audiobookshelf server. When you access your server through a browser, Cloudflare prompts you to log in (via email OTP, Google, etc.). But apps can’t do that browser-based flow.

Instead, apps use Service Tokens - a Client ID and Secret that bypass the Cloudflare login and go straight to your server. You still need your Audiobookshelf username and password after that.

Step 1: Create a Service Token

  1. Go to Cloudflare Zero Trust Dashboard
  2. Navigate to Access → Service Auth → Service Tokens
  3. Click Create Service Token
  4. Name it something like “SoundLeaf iOS”
  5. Copy both values:
    • CF-Access-Client-Id
    • CF-Access-Client-Secret

Important: The secret is only shown once. Save it somewhere secure.

Step 2: Add a Service Auth Policy

This is the step most people miss. Your service token needs a Service Auth policy, not just an Allow policy.

  1. Go to Access → Applications
  2. Select your Audiobookshelf application
  3. Go to Policies tab
  4. Click Add a policy
  5. Set:
    • Policy name: “Service Token Access”
    • Action: Service Auth (not Allow!)
    • Include: Service Token → select the token you created

Step 3: Configure SoundLeaf

  1. Open SoundLeaf
  2. On the login screen, tap Headers
  3. Tap Add from template and select CF-Access-Client-Id
  4. Paste your Client ID value
  5. Tap Add from template again and select CF-Access-Client-Secret
  6. Paste your Client Secret value
  7. Make sure both headers are enabled (toggle on)
  8. Tap Done

Now enter your server URL and Audiobookshelf credentials as usual.

Troubleshooting

”Login failed” or “Connection failed”

  • Double-check your Client ID and Secret are correct (no extra spaces)
  • Verify the headers are enabled (green toggle)
  • Ensure you created a Service Auth policy, not just an Allow policy

Images or playback not working

SoundLeaf sends these headers with every request, including images and audio streams. If you’re having issues:

  • Check your Cloudflare session duration isn’t too short
  • Verify the service token policy applies to the entire application, not just specific paths

Still stuck?

Check the Cloudflare Zero Trust docs for more details on service tokens.