# Cloudflare Access Setup

> Connect SoundLeaf to your Audiobookshelf server behind Cloudflare Zero Trust

Source: https://soundleafapp.com/docs/cloudflare-access-setup/

---

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](https://one.dash.cloudflare.com/)
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](https://developers.cloudflare.com/cloudflare-one/identity/service-tokens/) for more details on service tokens.