> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newly.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions & Entitlements

> Some app capabilities need approval from Apple or Google before you can ship them. Here's how to apply.

# Permissions & Entitlements

Most permissions your app needs — camera, location, notifications, photos — work as soon as you add them and ask the user. But a small set of powerful capabilities are **gated**: Apple or Google requires a separate application or declaration, and your app will be **rejected at submission** if you ship the capability without it.

This page explains which capabilities are gated, how to apply for each, and how to add the capability to your app in Newly.

<Note>
  This page is **only** about approval-gated capabilities. Everyday permissions like camera, microphone, location, contacts and push notifications need no special approval — just add them and the OS prompts the user at runtime.
</Note>

## How gating works

There are three different gates, and knowing which one applies tells you what to do:

<CardGroup cols={3}>
  <Card title="Apple request form" icon="file-signature">
    You fill out an Apple form and wait for approval **before** the entitlement can be used in a distribution build.
  </Card>

  <Card title="Apple App Review" icon="apple">
    No form — you enable the capability in your build, and Apple checks it during normal **App Review**.
  </Card>

  <Card title="Play Console declaration" icon="google-play">
    You complete a **Permissions Declaration** inside Google Play Console before the app or update can publish.
  </Card>
</CardGroup>

## Apple: managed entitlements

These Apple capabilities require a **request form** and approval before you can ship a distribution build. Each links to a deeper guide.

| Capability                                                   | What it's for                                          | Apply via                                                                                                          |
| ------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| [Family Controls](/articles/family-controls-entitlement)     | Screen Time, app blocking, parental controls           | [Family Controls (Distribution) request](https://developer.apple.com/contact/request/family-controls-distribution) |
| [Critical Alerts](/articles/critical-alerts-entitlement)     | Notifications that bypass silent mode & Focus          | [Critical Alerts request](https://developer.apple.com/contact/request/notifications-critical-alerts-entitlement/)  |
| [CarPlay](/articles/carplay-entitlement)                     | In-car app UI (audio, navigation, EV charging…)        | [Request a CarPlay entitlement](https://developer.apple.com/contact/carplay/)                                      |
| [Network Extension](/articles/network-extension-entitlement) | Hotspot Helper (VPN/content-filter are now self-serve) | [Network Extension request](https://developer.apple.com/contact/request/network-extension)                         |

A few Apple capabilities are gated at **App Review** instead — there's no form, but you must meet documented requirements:

| Capability                                             | What it's for                                                         | How it's gated                                    |
| ------------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------- |
| [Health Records](/articles/health-records-entitlement) | Reading a user's clinical / FHIR health records                       | Enable in Xcode → justify at App Review           |
| [Default App](/articles/ios-default-app-entitlement)   | Default calling, messaging, navigation or translation app (iOS 18.2+) | Enable in Xcode → meet requirements at App Review |

### The Apple request flow

For the form-gated entitlements above, the process is the same:

<Steps>
  <Step title="Develop against the capability first">
    Many entitlements (like Family Controls) provide a development variant you can build and test with locally before you request distribution.
  </Step>

  <Step title="Sign in as the Account Holder">
    Open the request form while signed in to the Apple Developer account that owns the app — requests are tied to your team.
  </Step>

  <Step title="Describe your app and use case">
    Provide the bundle identifier and a clear, specific justification for why the app needs the capability and how it uses it.
  </Step>

  <Step title="Wait for review">
    Apple reviews each request manually — typically a few business days to a few weeks. Submit early.
  </Step>

  <Step title="Enable the capability and rebuild">
    Once approved, turn the capability on for your bundle ID, regenerate your distribution provisioning profile, and rebuild.
  </Step>
</Steps>

<Warning>
  Approval must happen **before** you submit to the App Store. The development build can work locally while you wait, but uploading a distribution build with an unapproved managed entitlement will fail signing or be rejected.
</Warning>

## Android: restricted permissions

Google Play classifies some permissions as high-risk. Requesting one triggers a **Permissions Declaration** in Play Console, and in most cases you need approval before the app or any update can publish. See the [full guide](/articles/android-restricted-permissions) for details.

| Permission                   | What it covers              | Declaration required?                                  |
| ---------------------------- | --------------------------- | ------------------------------------------------------ |
| `BIND_ACCESSIBILITY_SERVICE` | Accessibility API           | Always, unless it's a genuine accessibility tool       |
| `READ_SMS` / `READ_CALL_LOG` | SMS & call history          | Always (must be default handler or approved exception) |
| `ACCESS_BACKGROUND_LOCATION` | Location while backgrounded | Always                                                 |
| `MANAGE_EXTERNAL_STORAGE`    | All Files Access            | Always                                                 |
| `QUERY_ALL_PACKAGES`         | See all installed apps      | When broad visibility is requested                     |

<Steps>
  <Step title="Audit your compiled manifest">
    A library or config plugin can pull in a sensitive permission you didn't add directly. Review the merged `AndroidManifest.xml` (or `expo prebuild` output) before you submit.
  </Step>

  <Step title="Open the declaration in Play Console">
    Go to **App content → Sensitive app permissions / Permissions Declaration Form**. It also surfaces automatically during a release that requests an undeclared sensitive permission.
  </Step>

  <Step title="Justify the core use case">
    Select the supported use case, explain why the permission is essential, and why a privacy-friendlier alternative won't work.
  </Step>

  <Step title="Provide a video demonstration">
    Add a short video showing the permission in use, plus test instructions or a test account.
  </Step>

  <Step title="Submit and wait for extended review">
    The release sits in pending publication during extended review — Google says this can take up to several weeks.
  </Step>
</Steps>

<Warning>
  If you don't declare a restricted permission, you **can't publish updates**, and a non-compliant live app can be removed from Google Play.
</Warning>

## Adding the entitlement in Newly

Newly builds real native apps, so a gated capability goes into your project the same way it would in a hand-written app — you just describe it.

<Tabs>
  <Tab title="Via AI">
    Describe the capability in your project chat, for example:

    ```
    Add the Family Controls entitlement so users can block
    selected apps during focus sessions.
    ```

    The agent wires up the entitlement keys, `Info.plist` / `AndroidManifest` entries and native modules for you.
  </Tab>

  <Tab title="Then apply & rebuild">
    1. File the Apple request (or complete the Play Console declaration) yourself — only your developer account can do this.
    2. Once approved, open **More → Deploy App** and rebuild.
    3. Submit to the App Store / Play Store. The entitlement is already in your build, so it's ready the moment approval lands.
  </Tab>
</Tabs>

<Tip>
  File the approval request **early** — it often takes longer than the build itself. You can keep developing while you wait.
</Tip>

## Still have questions?

* **Ask the AI** in your project chat — describe the capability you need and it can help wire it up.
* **Email us** at [support@newly.app](mailto:support@newly.app).

<Card title="App Deployment" icon="rocket" href="/features/deployment">
  How Newly builds and submits your app to the App Store and Play Store.
</Card>