​

Permissions

​

Overview

// Example: Your app automatically receives permission information in session
protected async onSession(session: AppSession, sessionId: string, userId: string): Promise<void> {
  // Subscribe to transcription events (requires MICROPHONE permission)
  session.events.onTranscription((data) => {
    console.log('User said:', data.text);
  });

  // Subscribe to location updates (requires LOCATION permission)
  session.events.onLocationUpdate((data) => {
    console.log('User location:', data.lat, data.lng);
  });
}

​

How Permissions Work

1. Declaration Level: You declare which permissions your app needs in the MentraOS Developer Console
2. Runtime Level: The system automatically enforces these permissions when your app tries to access protected data streams

• The system checks if your app has declared the necessary permissions for the data streams it’s trying to access
• If device-level permissions (like microphone access) are disabled, your app receives error messages
• Users see exactly what data your app can access based on your permission declarations

​

Declaring Permissions

​

Using the Developer Console

1. Log in to the MentraOS Developer Console
2. Navigate to your app’s settings page
3. Scroll to the Required Permissions section
4. Click Add Permission to add a new permission
5. Select the permission type from the dropdown
6. Add a description explaining why your app needs this permission. This is shown to the user when they install your app.
7. Save your changes

​

Available Permission Types

​

1. MICROPHONE

• Purpose: Access to audio recording and speech processing
• Data Streams Enabled:
  • TRANSCRIPTION - Real-time speech-to-text conversion
  • TRANSLATION - Language translation of speech
  • AUDIO_CHUNK - Raw audio data for advanced processing
  • VAD - Voice activity detection
  • Language-specific streams (e.g., transcription:en, translation:fr)
• Common Use Cases: Voice assistants, transcription apps, language translation, voice commands

// Example: Using microphone permission
session.events.onTranscription((data) => {
  if (data.isFinal) {
    console.log('User said:', data.text);
    // Process the transcribed text
  }
});

​

2. LOCATION

• Purpose: Access to device location services
• Data Streams Enabled:
  • LOCATION_UPDATE - Real-time GPS coordinates
• Common Use Cases: Navigation apps, location-based reminders, weather apps, local search

// Example: Using location permission
session.location.subscribeToStream({ accuracy: 'high' }, (data) => {
  console.log(`User is at: ${data.lat}, ${data.lng}`);
  // Update location-based features
});

​

3. CALENDAR

• Purpose: Access to device calendar events
• Data Streams Enabled:
  • CALENDAR_EVENT - Calendar event information
• Common Use Cases: Schedule management, meeting reminders, productivity apps

// Example: Using calendar permission
session.events.on<CalendarEvent>(StreamType.CALENDAR_EVENT, (data) => {
  console.log('Upcoming event:', data.title);
  // Display calendar information
});

​

4. CAMERA

• Purpose: Access to camera for photo capture and video streaming
• Data Streams Enabled:
  • PHOTO_RESPONSE - Photo capture responses
  • PHOTO_TAKEN - Photo capture events
  • RTMP_STREAM_STATUS - RTMP streaming status updates
  • MANAGED_STREAM_STATUS - Managed streaming status updates
• Common Use Cases: Photo documentation, live streaming, video recording, security monitoring

// Example: Using camera permission
session.camera.requestPhoto({ saveToGallery: true }).then((photo) => {
  console.log('Photo captured:', photo.filename);
  // Process the captured photo
});

// Start streaming
session.camera.startStream({
  rtmpUrl: 'rtmp://example.com/live/stream-key'
});

​

5. READ_NOTIFICATIONS

• Purpose: Access to device notifications
• Data Streams Enabled:
  • PHONE_NOTIFICATION - Incoming notification data
  • NOTIFICATION_DISMISSED - Notification dismissal events
• Common Use Cases: Notification filtering, smart alerts, communication apps

// Example: Using notifications permission
session.events.onPhoneNotification((data) => {
  console.log(`New notification from ${data.app}: ${data.title}`);
  // Process or filter notifications
});

​

Permission Enforcement

​

Automatic Stream Filtering

1. Permission Declaration: Does your app declare the required permission?
2. Device Permission Status: Is the corresponding device permission enabled?
3. Access Decision: Grant or deny access based on both criteria

// If your app hasn't declared MICROPHONE permission, this will fail
session.events.onTranscription((data) => {
  // This handler will never be called without MICROPHONE permission
});

​

Error Handling

// Listen for permission-related errors
session.events.on('permission_denied', (data) => {
  console.log(`Cannot access ${data.stream} - ${data.permission} permission required`);
  // Provide alternative functionality or user guidance
});

​

Best Practices

​

1. Minimize Permissions

// ✅ Good: Only request what you need
{
  "permissions": [
    { "type": "MICROPHONE", "description": "For voice commands" }
  ]
}

​

2. Provide Clear Descriptions

// ✅ Good: Clear, specific description
{
  "type": "LOCATION",
  "description": "Used to provide weather information for your current location"
}

// ❌ Avoid: Vague or missing description
{
  "type": "LOCATION"
}

​

3. Respect User Privacy

• Only access the data you actually use
• Process sensitive data securely
• Be transparent about data usage in your app description