--- description: Capacitor plugin to check and request device permissions such as camera, location, contacts, and notifications through a single unified API. Supports Android, iOS, and the web (partial). title: Capacitor Permissions Plugin - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/permissions.png --- [Skip to content ](#capacitor-permissions-plugin) [πŸ“² Introducing **Build Sharing** β€” get your builds onto testers' devices with a link & QR code. No account required. ](/blog/share-mobile-app-builds-with-testers/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * Permissions [ Permissions ](/docs/sdks/capacitor/permissions/) * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Enums ](#enums) * [ Platform behavior ](#platform-behavior) * [ Requesting background location ](#requesting-background-location) * [ Recovering from denied permissions ](#recovering-from-denied-permissions) * [ App Tracking Transparency ](#app-tracking-transparency) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Enums ](#enums) * [ Platform behavior ](#platform-behavior) * [ Requesting background location ](#requesting-background-location) * [ Recovering from denied permissions ](#recovering-from-denied-permissions) * [ App Tracking Transparency ](#app-tracking-transparency) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) # Capacitor Permissions Plugin[ΒΆ](#capacitor-permissions-plugin "Permanent link") Capacitor plugin to check and request device permissions with a unified API. [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Features[ΒΆ](#features "Permanent link") * πŸ–₯️ **Cross-platform**: Supports Android, iOS and Web (partial). * 🧩 **Unified API**: Check and request many different permissions with a single API instead of installing a feature plugin for each one. * πŸ—‚οΈ **Curated catalog**: Supports Bluetooth, calendar, camera, contacts, location, background location, microphone, motion, notifications, photos and reminders. * πŸ” **Prompt-free checks**: The `check(...)` method never triggers a permission prompt. * πŸͺΆ **Lightweight**: The plugin does not declare any permissions itself. Your app only declares the permissions it actually uses. * 🀝 **Compatibility**: Works alongside the [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) and [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/) plugins. * πŸ“¦ **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. * πŸ” **Up-to-date**: Always supports the latest Capacitor version. * ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases[ΒΆ](#use-cases "Permanent link") The Permissions plugin is typically used whenever an app needs to manage several device permissions in one place, for example: * **Onboarding screens**: Check the states of all permissions your app uses with the prompt-free `check(...)` method and present them in a single overview. * **Contextual permission requests**: Request the camera or microphone permission right before the user starts a video call or recording. * **Background location upgrades**: Request the `LOCATION` permission first and upgrade to `LOCATION_ALWAYS` afterwards, as recommended by the platforms. * **Recovering from denied permissions**: Detect the `denied` state and guide the user to the app settings to re-enable the permission. ## Compatibility[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | \>=8.x.x | Active support | ## Installation[ΒΆ](#installation "Permanent link") You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: `[](#%5F%5Fcodelineno-0-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-1-1) Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-permissions` plugin in my project. `` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: `[](#%5F%5Fcodelineno-2-1)npm install @capawesome/capacitor-permissions [](#%5F%5Fcodelineno-2-2)npx cap sync ` **Attention**: The plugin itself does **not** declare any permissions and does **not** require any Info.plist keys. Your app must declare exactly the permissions it actually uses (see below). This way, your app does not request permissions it does not need. ### Android[ΒΆ](#android "Permanent link") #### Permissions[ΒΆ](#permissions "Permanent link") Add the manifest entries for the permissions you want to check or request to your `AndroidManifest.xml` file before or after the `application` tag. If a permission is not declared, the `request(...)` method rejects with a clear error message. | Permission | Required manifest entries | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | BLUETOOTH | android.permission.BLUETOOTH\_SCAN, android.permission.BLUETOOTH\_CONNECT | | CALENDAR | android.permission.READ\_CALENDAR, android.permission.WRITE\_CALENDAR | | CAMERA | android.permission.CAMERA | | CONTACTS | android.permission.READ\_CONTACTS, android.permission.WRITE\_CONTACTS | | LOCATION | android.permission.ACCESS\_COARSE\_LOCATION, android.permission.ACCESS\_FINE\_LOCATION | | LOCATION\_ALWAYS | android.permission.ACCESS\_BACKGROUND\_LOCATION (plus the LOCATION entries) | | MICROPHONE | android.permission.RECORD\_AUDIO | | MOTION | android.permission.ACTIVITY\_RECOGNITION | | NOTIFICATIONS | android.permission.POST\_NOTIFICATIONS | | PHOTOS | android.permission.READ\_MEDIA\_IMAGES, android.permission.READ\_MEDIA\_VISUAL\_USER\_SELECTED, android.permission.READ\_EXTERNAL\_STORAGE (max SDK version 32) | | REMINDERS | Not available on Android. | **Example**: `` [](#%5F%5Fcodelineno-3-1) [](#%5F%5Fcodelineno-3-2) [](#%5F%5Fcodelineno-3-3) [](#%5F%5Fcodelineno-3-4) [](#%5F%5Fcodelineno-3-5) [](#%5F%5Fcodelineno-3-6) [](#%5F%5Fcodelineno-3-7) [](#%5F%5Fcodelineno-3-8) [](#%5F%5Fcodelineno-3-9) [](#%5F%5Fcodelineno-3-10) [](#%5F%5Fcodelineno-3-11) [](#%5F%5Fcodelineno-3-12) [](#%5F%5Fcodelineno-3-13) [](#%5F%5Fcodelineno-3-14) [](#%5F%5Fcodelineno-3-15) [](#%5F%5Fcodelineno-3-16) [](#%5F%5Fcodelineno-3-17) [](#%5F%5Fcodelineno-3-18) [](#%5F%5Fcodelineno-3-19) [](#%5F%5Fcodelineno-3-20) [](#%5F%5Fcodelineno-3-21) [](#%5F%5Fcodelineno-3-22) [](#%5F%5Fcodelineno-3-23) [](#%5F%5Fcodelineno-3-24) [](#%5F%5Fcodelineno-3-25) [](#%5F%5Fcodelineno-3-26) `` ### iOS[ΒΆ](#ios "Permanent link") #### Privacy Descriptions[ΒΆ](#privacy-descriptions "Permanent link") Add the usage description keys for the permissions you want to request to the `ios/App/App/Info.plist` file. If a key is missing, the `request(...)` method rejects with a clear error message. | Permission | Required Info.plist keys | | ---------------- | ----------------------------------------------------------------------------------------------- | | BLUETOOTH | NSBluetoothAlwaysUsageDescription | | CALENDAR | NSCalendarsFullAccessUsageDescription (iOS 17+), NSCalendarsUsageDescription (iOS 16 and older) | | CAMERA | NSCameraUsageDescription | | CONTACTS | NSContactsUsageDescription | | LOCATION | NSLocationWhenInUseUsageDescription | | LOCATION\_ALWAYS | NSLocationAlwaysAndWhenInUseUsageDescription, NSLocationWhenInUseUsageDescription | | MICROPHONE | NSMicrophoneUsageDescription | | MOTION | NSMotionUsageDescription | | NOTIFICATIONS | None | | PHOTOS | NSPhotoLibraryUsageDescription | | REMINDERS | NSRemindersFullAccessUsageDescription (iOS 17+), NSRemindersUsageDescription (iOS 16 and older) | **Example**: `[](#%5F%5Fcodelineno-4-1)NSCameraUsageDescription [](#%5F%5Fcodelineno-4-2)The camera is used to take photos. [](#%5F%5Fcodelineno-4-3)NSMicrophoneUsageDescription [](#%5F%5Fcodelineno-4-4)The microphone is used to record audio. ` **Note**: Since the plugin references the system frameworks of all supported permissions, App Store Connect may ask you to provide additional usage descriptions when you upload your app, even if you do not request those permissions. ## Configuration[ΒΆ](#configuration "Permanent link") No configuration required for this plugin. ## Usage[ΒΆ](#usage "Permanent link") The following examples show how to check the states of one or more permissions and how to request them from the user. ### Check the states of one or more permissions[ΒΆ](#check-the-states-of-one-or-more-permissions "Permanent link") Use the `check(...)` method to read the current states of one or more permissions. This method never displays a permission prompt, so it is safe to call at any time, for example to build an onboarding or settings screen: `[](#%5F%5Fcodelineno-5-1)import { Permission, Permissions } from '@capawesome/capacitor-permissions'; [](#%5F%5Fcodelineno-5-2) [](#%5F%5Fcodelineno-5-3)const checkPermissions = async () => { [](#%5F%5Fcodelineno-5-4) const { statuses } = await Permissions.check({ [](#%5F%5Fcodelineno-5-5) permissions: [Permission.Camera, Permission.Microphone], [](#%5F%5Fcodelineno-5-6) }); [](#%5F%5Fcodelineno-5-7) return statuses; [](#%5F%5Fcodelineno-5-8)}; ` ### Request one or more permissions[ΒΆ](#request-one-or-more-permissions "Permanent link") Use the `request(...)` method to prompt the user for one or more permissions. Permissions that are already granted or that cannot be requested on the current platform are not requested again; in that case, the current state is returned. On the web, only the `NOTIFICATIONS` permission can be requested: `[](#%5F%5Fcodelineno-6-1)import { Permission, Permissions } from '@capawesome/capacitor-permissions'; [](#%5F%5Fcodelineno-6-2) [](#%5F%5Fcodelineno-6-3)const requestPermissions = async () => { [](#%5F%5Fcodelineno-6-4) const { statuses } = await Permissions.request({ [](#%5F%5Fcodelineno-6-5) permissions: [Permission.Camera, Permission.Microphone], [](#%5F%5Fcodelineno-6-6) }); [](#%5F%5Fcodelineno-6-7) return statuses; [](#%5F%5Fcodelineno-6-8)}; ` ## API[ΒΆ](#api "Permanent link") * [check(...)](#check) * [request(...)](#request) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### check(...)[ΒΆ](#check "Permanent link") `[](#%5F%5Fcodelineno-7-1)check(options: CheckOptions) => Promise ` Check the current states of one or more permissions. This method never displays a permission prompt. | Param | Type | | ----------- | ----------------------------- | | **options** | [CheckOptions](#checkoptions) | **Returns:** `Promise<[CheckResult](#checkresult)>` **Since:** 0.1.0 --- ### request(...)[ΒΆ](#request "Permanent link") `[](#%5F%5Fcodelineno-8-1)request(options: RequestOptions) => Promise ` Request one or more permissions from the user. Permissions that are already granted or that cannot be requested on the current platform are not requested again. In this case, the current state of the permission is returned. On Android, the corresponding permissions must be declared in the `AndroidManifest.xml` file of your app. Otherwise, the call is rejected. On iOS, the corresponding usage descriptions must be provided in the `Info.plist` file of your app. Otherwise, the call is rejected. On the web, only the `NOTIFICATIONS` permission can be requested. For all other permissions, the current state is returned since browsers display the permission prompt when the corresponding web API is used for the first time. | Param | Type | | ----------- | --------------------------------- | | **options** | [RequestOptions](#requestoptions) | **Returns:** `Promise<[RequestResult](#requestresult)>` **Since:** 0.1.0 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### CheckResult[ΒΆ](#checkresult "Permanent link") | Prop | Type | Description | Since | | ------------ | -------------------- | ------------------------------------------------------------------------------------ | ----- | | **statuses** | PermissionStatus\[\] | The states of the checked permissions in the same order as the provided permissions. | 0.1.0 | #### PermissionStatus[ΒΆ](#permissionstatus "Permanent link") | Prop | Type | Description | Since | | -------------- | ----------------------------------- | --------------------------------------------- | ----- | | **permission** | [Permission](#permission) | The permission that was checked or requested. | 0.1.0 | | **state** | [PermissionState](#permissionstate) | The state of the permission. | 0.1.0 | #### CheckOptions[ΒΆ](#checkoptions "Permanent link") | Prop | Type | Description | Since | | --------------- | -------------- | ------------------------- | ----- | | **permissions** | Permission\[\] | The permissions to check. | 0.1.0 | #### RequestResult[ΒΆ](#requestresult "Permanent link") | Prop | Type | Description | Since | | ------------ | -------------------- | -------------------------------------------------------------------------------------- | ----- | | **statuses** | PermissionStatus\[\] | The states of the requested permissions in the same order as the provided permissions. | 0.1.0 | #### RequestOptions[ΒΆ](#requestoptions "Permanent link") | Prop | Type | Description | Since | | --------------- | -------------- | --------------------------- | ----- | | **permissions** | Permission\[\] | The permissions to request. | 0.1.0 | ### Type Aliases[ΒΆ](#type-aliases "Permanent link") #### PermissionState[ΒΆ](#permissionstate "Permanent link") `'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'` ### Enums[ΒΆ](#enums "Permanent link") #### Permission[ΒΆ](#permission "Permanent link") | Members | Value | Description | Since | | ------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **Bluetooth** | 'BLUETOOTH' | [Permission](#permission) to use Bluetooth. On Android 12 (API level 31) and later, this covers the BLUETOOTH\_SCAN and BLUETOOTH\_CONNECT permissions. On older Android versions, no runtime permission is required and the state is always granted. On the web, this permission is not available. | 0.1.0 | | **Calendar** | 'CALENDAR' | [Permission](#permission) to read and write calendar events. On iOS 17 and later, write-only access is reported as limited. On the web, this permission is not available. | 0.1.0 | | **Camera** | 'CAMERA' | [Permission](#permission) to use the camera. | 0.1.0 | | **Contacts** | 'CONTACTS' | [Permission](#permission) to read and write contacts. On iOS 18 and later, limited access is reported as limited. On the web, this permission is not available. | 0.1.0 | | **Location** | 'LOCATION' | [Permission](#permission) to access the location while the app is in use. On Android 12 (API level 31) and later, the user may grant only approximate location access. In this case, the state is still reported as granted. | 0.1.0 | | **LocationAlways** | 'LOCATION\_ALWAYS' | [Permission](#permission) to access the location even while the app is in the background. This permission should only be requested after the LOCATION permission has been granted. On the web, this permission is not available. | 0.1.0 | | **Microphone** | 'MICROPHONE' | [Permission](#permission) to use the microphone. | 0.1.0 | | **Motion** | 'MOTION' | [Permission](#permission) to access motion and fitness data. On Android 10 (API level 29) and later, this covers the ACTIVITY\_RECOGNITION permission. On older Android versions, no runtime permission is required and the state is always granted. On the web, this permission is not available. | 0.1.0 | | **Notifications** | 'NOTIFICATIONS' | [Permission](#permission) to display notifications. On Android 13 (API level 33) and later, this covers the POST\_NOTIFICATIONS permission. On older Android versions, no runtime permission is required and the state is always granted. | 0.1.0 | | **Photos** | 'PHOTOS' | [Permission](#permission) to access the photo library. On Android 14 (API level 34) and later and on iOS, partial access to the photo library is reported as limited. On the web, this permission is not available. | 0.1.0 | | **Reminders** | 'REMINDERS' | [Permission](#permission) to read and write reminders. Only available on iOS. | 0.1.0 | ## Platform behavior[ΒΆ](#platform-behavior "Permanent link") The following table summarizes the behavior of each permission on each platform: | Permission | Android | iOS | Web | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------- | | BLUETOOTH | Covers BLUETOOTH\_SCAN and BLUETOOTH\_CONNECT on Android 12+. On older versions, always granted. | Covers the Core Bluetooth authorization. | Always unavailable. | | CALENDAR | Covers READ\_CALENDAR and WRITE\_CALENDAR. | On iOS 17+, write-only access is reported as limited. | Always unavailable. | | CAMERA | Covers CAMERA. | Covers the camera authorization. | Check supported. Request returns the current state. | | CONTACTS | Covers READ\_CONTACTS and WRITE\_CONTACTS. | On iOS 18+, limited access is reported as limited. | Always unavailable. | | LOCATION | Covers ACCESS\_COARSE\_LOCATION and ACCESS\_FINE\_LOCATION. Reported as granted if at least approximate location access has been granted. | Covers the when-in-use location authorization. | Check supported. Request returns the current state. | | LOCATION\_ALWAYS | Covers ACCESS\_BACKGROUND\_LOCATION on Android 10+. On older versions, behaves like LOCATION. | Covers the always location authorization. iOS only displays the upgrade prompt once. | Always unavailable. | | MICROPHONE | Covers RECORD\_AUDIO. | Covers the microphone authorization. | Check supported. Request returns the current state. | | MOTION | Covers ACTIVITY\_RECOGNITION on Android 10+. On older versions, always granted. | Covers the motion activity authorization. Requires a real device. | Always unavailable. | | NOTIFICATIONS | Covers POST\_NOTIFICATIONS on Android 13+. On older versions, always granted. | Covers the notifications authorization. | Check and request supported. | | PHOTOS | Covers READ\_MEDIA\_IMAGES (and READ\_MEDIA\_VISUAL\_USER\_SELECTED) on Android 13+ and READ\_EXTERNAL\_STORAGE on older versions. Partial access is reported as limited. | Partial access is reported as limited. | Always unavailable. | | REMINDERS | Always unavailable. | Covers the reminders authorization. | Always unavailable. | ## Requesting background location[ΒΆ](#requesting-background-location "Permanent link") The `LOCATION_ALWAYS` permission should only be requested after the `LOCATION` permission has been granted: 1. Request the `LOCATION` permission and explain why you need location access. 2. Once granted, request the `LOCATION_ALWAYS` permission. On Android 11 and later, the system does not display a prompt for background location. Instead, the user is taken to the system settings to select the "Allow all the time" option. If the `LOCATION` permission has not been granted yet, the request is denied immediately by the system. On iOS, the system only displays the upgrade prompt from when-in-use to always access once. If the user has already made a decision, the current state is returned. ## Recovering from denied permissions[ΒΆ](#recovering-from-denied-permissions "Permanent link") If a permission is in the `denied` state, it can no longer be requested from within the app. In this case, you can guide the user to the app settings using the [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) plugin: `[](#%5F%5Fcodelineno-9-1)import { SettingsLauncher } from '@capawesome/capacitor-settings-launcher'; [](#%5F%5Fcodelineno-9-2) [](#%5F%5Fcodelineno-9-3)const openAppSettings = async () => { [](#%5F%5Fcodelineno-9-4) await SettingsLauncher.openAppSettings(); [](#%5F%5Fcodelineno-9-5)}; ` ## App Tracking Transparency[ΒΆ](#app-tracking-transparency "Permanent link") The App Tracking Transparency permission is deliberately not part of this plugin. Use the [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/) plugin instead. ## FAQ[ΒΆ](#faq "Permanent link") ### How is this plugin different from other similar plugins?[ΒΆ](#how-is-this-plugin-different-from-other-similar-plugins "Permanent link") It brings many device permissions under one unified, fully typed API β€” Bluetooth, calendar, camera, contacts, location, background location, microphone, motion, notifications, photos and reminders β€” so you check and request them all in one place. The `check(...)` method never triggers a system prompt, and the plugin declares no permissions itself, so your app only ships the ones it actually uses. It is handcrafted with care, works across Android, iOS and the Web (partial), and stays current with the latest Capacitor version. ### Does the `check` method trigger a permission prompt?[ΒΆ](#does-the-check-method-trigger-a-permission-prompt "Permanent link") No, the `check(...)` method never displays a permission prompt. It only reads the current states of the given permissions, so you can safely call it at any time, for example to build an onboarding or settings screen. ### Why does the `request` method reject with an error?[ΒΆ](#why-does-the-request-method-reject-with-an-error "Permanent link") On Android, the corresponding permissions must be declared in the `AndroidManifest.xml` file of your app. On iOS, the corresponding usage description keys must be provided in the `Info.plist` file of your app. If a declaration is missing, the `request(...)` method rejects with a clear error message. See the [Installation](#installation) section for the required entries per permission. ### Do I need to declare all supported permissions in my app?[ΒΆ](#do-i-need-to-declare-all-supported-permissions-in-my-app "Permanent link") No, the plugin itself does not declare any permissions and does not require any Info.plist keys. Your app only declares exactly the permissions it actually uses. This way, your app does not request permissions it does not need. ### How do I request background location access?[ΒΆ](#how-do-i-request-background-location-access "Permanent link") Request the `LOCATION` permission first and, once it has been granted, request the `LOCATION_ALWAYS` permission. On Android 11 and later, the system does not display a prompt for background location; instead, the user is taken to the system settings to select the "Allow all the time" option. On iOS, the system only displays the upgrade prompt from when-in-use to always access once. ### What can I do if a permission is denied?[ΒΆ](#what-can-i-do-if-a-permission-is-denied "Permanent link") If a permission is in the `denied` state, it can no longer be requested from within the app. In this case, you can guide the user to the app settings using the [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/) plugin so they can grant the permission manually. ### Which permissions are supported on the web?[ΒΆ](#which-permissions-are-supported-on-the-web "Permanent link") On the web, only the `NOTIFICATIONS` permission can be checked and requested. The `CAMERA`, `LOCATION` and `MICROPHONE` permissions support checking, while requesting returns the current state since browsers display the permission prompt when the corresponding web API is used for the first time. All other permissions are reported as `unavailable`. See the [Platform behavior](#platform-behavior) section for details. ## Related Plugins[ΒΆ](#related-plugins "Permanent link") * [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/): Open native settings screens, for example to recover from denied permissions. * [App Tracking Transparency](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/): Request the App Tracking Transparency permission on iOS. ## Newsletter[ΒΆ](#newsletter "Permanent link") Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/permissions/CHANGELOG.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/permissions/LICENSE). July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/permissions/#article", "headline": "Capacitor Permissions Plugin", "name": "Capacitor Permissions Plugin", "description": "Capacitor plugin to check and request device permissions such as camera, location, contacts, and notifications through a single unified API. Supports Android, iOS, and the web (partial).", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/permissions/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/permissions/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/permissions/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/permissions/#software", "name": "Capacitor Permissions Plugin", "description": "Capacitor plugin to check and request device permissions such as camera, location, contacts, and notifications through a single unified API. Supports Android, iOS, and the web (partial).", "url": "https://capawesome.io/docs/sdks/capacitor/permissions/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "How is this plugin different from other similar plugins?", "acceptedAnswer": {"@type": "Answer", "text": "It brings many device permissions under one unified, fully typed API β€” Bluetooth, calendar, camera, contacts, location, background location, microphone, motion, notifications, photos and reminders β€” so you check and request them all in one place. The check(...) method never triggers a system prompt, and the plugin declares no permissions itself, so your app only ships the ones it actually uses. It is handcrafted with care, works across Android, iOS and the Web (partial), and stays current with the latest Capacitor version."}}, {"@type": "Question", "name": "Does the check method trigger a permission prompt?", "acceptedAnswer": {"@type": "Answer", "text": "No, the check(...) method never displays a permission prompt. It only reads the current states of the given permissions, so you can safely call it at any time, for example to build an onboarding or settings screen."}}, {"@type": "Question", "name": "Why does the request method reject with an error?", "acceptedAnswer": {"@type": "Answer", "text": "On Android, the corresponding permissions must be declared in the AndroidManifest.xml file of your app. On iOS, the corresponding usage description keys must be provided in the Info.plist file of your app. If a declaration is missing, the request(...) method rejects with a clear error message. See the Installation section for the required entries per permission."}}, {"@type": "Question", "name": "Do I need to declare all supported permissions in my app?", "acceptedAnswer": {"@type": "Answer", "text": "No, the plugin itself does not declare any permissions and does not require any Info.plist keys. Your app only declares exactly the permissions it actually uses. This way, your app does not request permissions it does not need."}}, {"@type": "Question", "name": "How do I request background location access?", "acceptedAnswer": {"@type": "Answer", "text": "Request the LOCATION permission first and, once it has been granted, request the LOCATION_ALWAYS permission. On Android 11 and later, the system does not display a prompt for background location; instead, the user is taken to the system settings to select the \"Allow all the time\" option. On iOS, the system only displays the upgrade prompt from when-in-use to always access once."}}, {"@type": "Question", "name": "What can I do if a permission is denied?", "acceptedAnswer": {"@type": "Answer", "text": "If a permission is in the denied state, it can no longer be requested from within the app. In this case, you can guide the user to the app settings using the Settings Launcher plugin so they can grant the permission manually."}}, {"@type": "Question", "name": "Which permissions are supported on the web?", "acceptedAnswer": {"@type": "Answer", "text": "On the web, only the NOTIFICATIONS permission can be checked and requested. The CAMERA, LOCATION and MICROPHONE permissions support checking, while requesting returns the current state since browsers display the permission prompt when the corresponding web API is used for the first time. All other permissions are reported as unavailable. See the Platform behavior section for details."}}], "url": "https://capawesome.io/docs/sdks/capacitor/permissions/"} ```