Permissions

Permissions are derived, not hand-maintained. Every SDK capability your handler subscribes to (capture_photo, transcription_incremental, record_audio, etc.) declares its own Android manifest permissions and iOS Info.plist keys, and the MCP server's getPermissions tool returns the exact set for your declared capability list. The agent calls getPermissions, gets the structured output, and writes the manifest and Info.plist for you — no developer needs to memorize that transcription_incremental requires NSSpeechRecognitionUsageDescription on iOS or that continuous-capture flows require FOREGROUND_SERVICE on Android. This page is the consolidated map: which capabilities require which keys, plus the always-required Bluetooth foundation and Meta DAT entitlements that every Ray-Ban Meta integration needs.

How permission derivation works

Three layers cooperate:

1. extentos.manifest.json's capabilities array declares what SDK primitives your handler uses — capture_photo, transcription_incremental, speak, video_frames, etc.
2. The derivation logic (in mcp-server/src/tools/util/permissions.ts) maps each capability name to its required permissions per platform.
3. getPermissions returns the full set, plus structured details (Android manifest entries, iOS plist key/value/reason tuples, foreground-service declarations, NotificationListenerService stubs).

The agent calls getPermissions({ capabilities, platform }) whenever the declared capability list changes. The MCP server returns:

{
  "android": {
    "permissions": ["android.permission.CAMERA", "android.permission.BLUETOOTH_CONNECT", "..."],
    "manifestEntries": ["<uses-permission android:name=\"android.permission.CAMERA\" />", "..."],
    "foregroundService": { "required": true, "types": ["camera"], "declaration": "<service android:name=\".CameraForegroundService\" … />", "devInstructions": "subclass GlassesForegroundService …" },
    "notificationListener": { "required": false, "declaration": null, "devInstructions": null },
    "minimumSdk": 31,
    "compileSdk": 35,
    "targetSdk": 34
  },
  "ios": {
    "plistKeys": [
      { "key": "NSCameraUsageDescription", "value": "...", "reason": "capture_photo / capture_video block ..." },
      { "key": "NSBluetoothAlwaysUsageDescription", "value": "...", "reason": "Required by Meta DAT SDK ..." }
    ]
  },
  "metaDat": {
    "scopes": ["glasses.connection", "glasses.camera.photo", "..."],
    "registrationRequired": true,
    "registrationSteps": ["..."]
  },
  "summary": "Android, 5 permissions (min SDK 31, target 34). Meta DAT registration required, 3 scopes."
}

generateConnectionModule writes the manifest and Info.plist using this output during initial scaffolding. validateIntegration re-checks alignment after every change to your declared capabilities.

At runtime, your installed agent has this live. Once Extentos's MCP server is registered with your agent, the agent calls getPermissions({ capabilities, platform }) and gets the exact Android permissions, manifest entries, foreground-service declarations, and iOS Info.plist keys scoped to your declared capabilities — no manual lookup needed. The static derivation tables below are the human-readable reference for pre-install evaluation, SEO, and out-of-context lookup; the live getPermissions response is authoritative when wiring a real project.

Android permissions

Always required

These are the foundation — every Extentos app on Android requests them, regardless of which capabilities you declare:

Derived from camera primitives

Derived from audio primitives

Derived from hardware events

Hardware events your handler subscribes to via glasses.runtime.events and pattern-matches the variants from:

Foreground-service requirement for continuous capture

Microphone-type and camera-type services differ, and getPermissions reflects that. The library ships GlassesForegroundService with foregroundServiceType="microphone" and declares it in its own manifest — for a mic-only footprint you don't declare anything, you just call GlassesForegroundService.start(context). A camera-type service is yours: subclass GlassesForegroundService (or write your own) and declare it, because the library can't declare a camera service on behalf of apps that don't use the camera. That's why getPermissions returns a declaration stub for camera footprints and none for mic-only ones.

Capabilities that capture continuously (video_frames, audio_chunks, transcription_incremental) require FOREGROUND_SERVICE because the capture continues across app backgrounding — Android 14+ enforces foreground-service types per category (camera, microphone). getPermissions returns the required foregroundServiceType set in the response so your agent can configure the service correctly. See searchDocs(topic: 'concurrency_modes') for the background-survival model.

NotificationListenerService for phone notifications

If your handler subscribes to phone_notification_forwarded events, the library's ExtentosNotificationListenerService must be declared in your manifest:

<service
    android:name="com.extentos.glasses.core.notifications.ExtentosNotificationListenerService"
    android:label="Notification Mirroring"
    android:permission="android.permission.BIND_NOTIFICATION_LISTENER_SERVICE"
    android:exported="false">
    <intent-filter>
        <action android:name="android.service.notification.NotificationListenerService" />
    </intent-filter>
</service>

getPermissions returns this declaration verbatim under notificationListener.declaration when it's needed. Critically, BIND_NOTIFICATION_LISTENER_SERVICE is a system-managed permission — your app cannot request it via the runtime permission API. The user must enable it manually:

Settings → Notifications → Notification access → toggle your app on

Use NotificationAccessHelper.openSettings(context) from the library to deep-link the user to the right screen.

SDK version requirements

These come from a single source of truth (mcp-server/src/tools/data/version.ts) so library bumps don't drift. minSdk and compileSdk are real floors — take them from getPermissions rather than hardcoding a guess. targetSdk is not a requirement: the library declares none, so the 34 above is the value this advice was derived against, not a value to copy into your build. Yours is your own choice — see install.

iOS Info.plist keys

Always required

Derived from camera primitives

Derived from audio primitives

Derived from hardware events

Privacy strings

getPermissions returns each plist key with three fields: key, value (the default privacy string), reason (which SDK capability triggered it). Defaults from mcp-server/src/tools/util/permissions.ts:

You can override these strings in your Info.plist — the App Store review process strongly prefers app-specific reasons over generic ones.

Meta DAT-specific iOS Info.plist keys

These are not derived from your declared capabilities — they're required by every app that uses a vendor transport, regardless of which camera/display capabilities it declares. generateConnectionModule writes them once during initial scaffolding.

A voice-only app needs none of them: it has no Meta DAT dependency at all, and its microphone and speaker are reached through the phone's own Bluetooth audio routing. Skip this whole section if you're on the voice path.

MWDAT dictionary

<key>MWDAT</key>
<dict>
    <key>MetaAppID</key><string>YOUR_META_APP_ID</string>
    <key>ClientToken</key><string>YOUR_CLIENT_TOKEN</string>
    <key>TeamID</key><string>YOUR_APPLE_TEAM_ID</string>
    <key>AppLinkURLScheme</key><string>yourapp</string>
    <key>DAMEnabled</key><false/>
</dict>

AppLinkURLScheme is a custom URL scheme (e.g. yourapp://), not a universal link. Meta DAT uses it for the registration callback from the Meta companion app.

CFBundleURLTypes

Must include the same scheme:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array><string>yourapp</string></array>
    </dict>
</array>

LSApplicationQueriesSchemes

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>fb-viewapp</string>
</array>

Required to query whether the Meta AI / Meta View companion app is installed.

UISupportedExternalAccessoryProtocols

<key>UISupportedExternalAccessoryProtocols</key>
<array>
    <string>com.meta.ar.wearable</string>
</array>

Declares Meta's external-accessory protocol — required for the BLE link.

UIBackgroundModes

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>bluetooth-peripheral</string>
    <string>external-accessory</string>
</array>

Those three are the vendor-transport set — a camera or display app needs them. A voice-only app needs none of them, but if the assistant must keep running while the app is backgrounded it needs audio instead:

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Add audio to the array as well if your app is both.

Required to maintain the glasses connection across app backgrounding.

Worked example — a wake-phrase photo-capture handler

A handler that subscribes to audio.transcriptions() for the wake phrase, calls camera.capturePhoto(), forwards to a vision LLM, and audio.speak()s the result. Capability declarations in the manifest:

manifest.capabilities = [
  "transcription_incremental",  // subscribe to audio.transcriptions()
  "capture_photo",              // camera.capturePhoto()
  "speak"                       // audio.speak()
]

getPermissions({ capabilities, platform: "android" }) returns:

→ 7 permissions. foregroundService.required: true (continuous transcription). notificationListener.required: false.

getPermissions({ capabilities, platform: "ios" }) returns these plist keys:

→ 4 plist keys. Plus the always-required Meta DAT-specific keys (MWDAT dict, CFBundleURLTypes, LSApplicationQueriesSchemes, UISupportedExternalAccessoryProtocols, UIBackgroundModes).

Runtime permission requests vs manifest declarations

Declaring permissions in the manifest / Info.plist isn't the same as having them granted at runtime:

• Android: CAMERA, RECORD_AUDIO, ACCESS_FINE_LOCATION, READ_PHONE_STATE, and BLUETOOTH_CONNECT (on Android 12+) are dangerous permissions — declared in the manifest, but also requested via ActivityCompat.requestPermissions at runtime. The library's ExtentosConnectionPage handles the runtime flow during pairing, and once a vendor transport is running the SDK requests BLUETOOTH_CONNECT and CAMERA itself through your activityProvider. Neither covers an app with no connection page — a voice app owns its RECORD_AUDIO request outright, and a camera app must grant BLUETOOTH_CONNECT before ExtentosGlasses.create(...) for the vendor arm to resolve at all. See the voice-assistant bootstrap.
• iOS: plist keys declare the permission and provide the privacy string the OS shows to the user. The OS prompts on first use (e.g., the first time the camera is accessed). The library handles this; you don't need a separate request flow.
• BIND_NOTIFICATION_LISTENER_SERVICE on Android is special: declared in the manifest, but cannot be requested programmatically. The user must toggle it on manually in system Settings. Use NotificationAccessHelper.openSettings(context) to deep-link them there.

Common gotchas

Android 12 (API 31) Bluetooth split

Pre-Android 12, BLUETOOTH and BLUETOOTH_ADMIN were normal permissions auto-granted at install. Android 12 split them into runtime-requested BLUETOOTH_CONNECT and BLUETOOTH_SCAN. Extentos targets API 31+ — the new permissions are required (no legacy fallback); the library handles the user prompt during pairing.

iOS NSBluetoothAlwaysUsageDescription even if your app doesn't expose Bluetooth in the UI

Meta DAT's BLE connection requires this key. Even if your app appears purely visual to the user, the absence of this key causes the DAT registration flow to crash silently on iOS 13+.

Audio on capture_video

VideoConfig lets you request an audio track on the captured video; if you do, RECORD_AUDIO (Android) / NSMicrophoneUsageDescription (iOS) is required too. The default is video-only — only request audio if your handler actually needs it.

Foreground service types on Android 14+

Android 14 enforces foregroundServiceType="camera" or ="microphone" per continuous-capture flow. getPermissions returns the right type set; if you write the manifest by hand, make sure the service declaration includes the matching type attribute.

Frequently asked questions

Why does Extentos derive permissions instead of letting me write them?

Three reasons. (1) Permissions drift the moment a handler changes which capability it subscribes to — adding transcription_incremental requires NSSpeechRecognitionUsageDescription, and forgetting to add it manifests as a confusing runtime crash. (2) Platform requirements evolve (Android 12 BT split, Android 14 foreground-service types) — centralized derivation lets the library track them. (3) AI agents can't reliably memorize platform permission rules; getPermissions is a deterministic primitive they can call.

Can I add permissions Extentos doesn't derive?

Yes. The getPermissions output is the minimum set Extentos needs for the declared capabilities. Your app can add more permissions for features outside the SDK (analytics, push notifications, etc.) by editing the manifest / Info.plist directly. validateIntegration flags missing required permissions but doesn't complain about extras.

What's the difference between BLUETOOTH_CONNECT and BLUETOOTH_SCAN on Android?

BLUETOOTH_CONNECT is for connecting to an already-paired device. BLUETOOTH_SCAN is for discovering nearby devices. Extentos requests both because the pairing flow scans for the glasses on first run, then connects to the bonded device on subsequent runs.

Why is NSBluetoothAlwaysUsageDescription required and not NSBluetoothPeripheralUsageDescription?

Apple deprecated NSBluetoothPeripheralUsageDescription in iOS 13 in favor of NSBluetoothAlwaysUsageDescription. Meta DAT v0.6+ requires the modern key.

Does my app need to declare every key Meta's documentation lists?

It depends on the path. The Meta DAT-specific keys (MWDAT dict, LSApplicationQueriesSchemes, UISupportedExternalAccessoryProtocols, UIBackgroundModes) are mandatory for any app that uses a vendor transport — that is, one declaring camera or display. A voice-only app has no DAT dependency at all and needs none of them; its microphone and speaker are reached through the phone's own Bluetooth audio routing.

What happens if I miss a permission?

• Android dangerous permissions (CAMERA, RECORD_AUDIO, etc.) — the runtime request fails silently; the library logs a permission.denied event into the structured event log; the affected capability's result is a typed failure. On the capture path that failure is CaptureError.PlatformError, not PermissionDenied — CaptureError.PermissionDenied is declared but not currently emitted, so don't hang your "ask for the camera again" recovery on it (see photo capture fails). Audio calls do return AudioError.PermissionDenied.
• iOS plist keys — the OS terminates your app the moment it tries to access the gated API. There's no graceful fallback — fix the plist.
• BIND_NOTIFICATION_LISTENER_SERVICE — declared but not granted means phone_notification_forwarded events never reach your handler. The library logs the gap; the user has to enable it in system Settings.

validateIntegration checks alignment between your declared capabilities and your manifest / Info.plist, and flags missing keys before testing.

Related concepts

• Architecture — how the SDK, library, and platform fit together; permissions are part of the boundary
• Capabilities — the vocabulary that drives permission derivation
• Vendors: Meta Ray-Ban — the Meta DAT-specific Info.plist keys, registration flow, audio architecture
• getPermissions tool — the MCP tool the agent calls to retrieve the current permission set
• Quickstart with an AI agent — how the agent wires permissions during initial scaffolding

Related