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

# Permissions

> REST endpoints for managing app permissions

## Get App Permissions

Retrieve permissions for a specific app.

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  GET https://api.mentra.glass/api/permissions/:packageName
  ```

  ```bash Development theme={null}
  GET https://devapi.mentra.glass/api/permissions/:packageName
  ```

  ```bash Local theme={null}
  GET http://localhost:8002/api/permissions/:packageName
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
X-Org-Id: <organizationId> (optional)
```

### Parameters

| Parameter     | Type   | Description                           |
| ------------- | ------ | ------------------------------------- |
| `packageName` | string | The app's package identifier (in URL) |

### Response

Success (200):

```json theme={null}
{
  "permissions": [
    {
      "type": "CAMERA",
      "description": "Take photos to analyze visual content"
    },
    {
      "type": "MICROPHONE",
      "description": "Listen to conversations for transcription"
    }
  ]
}
```

Error (403):

```json theme={null}
{
  "error": "Unauthorized",
  "message": "You do not have permission to view this app's permissions"
}
```

Error (404):

```json theme={null}
{
  "error": "App not found"
}
```

Error (500):

```json theme={null}
{
  "error": "Internal server error"
}
```

### Implementation

* **File**: `packages/cloud/src/routes/permissions.routes.ts:24-76`
* **Middleware**: `validateCoreToken`
* **Authorization**: Checks app ownership or published status

### Access Control

Users can view permissions if:

* App is published in the app store (`appStoreStatus === 'PUBLISHED'`)
* User's organization owns the app (via `X-Org-Id` header)
* User is the app developer (email matches `developerId`)
* User is member of the app's organization

## Update App Permissions

Update permissions for an app you own.

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  PATCH https://api.mentra.glass/api/permissions/:packageName
  ```

  ```bash Development theme={null}
  PATCH https://devapi.mentra.glass/api/permissions/:packageName
  ```

  ```bash Local theme={null}
  PATCH http://localhost:8002/api/permissions/:packageName
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
X-Org-Id: <organizationId> (optional)
Content-Type: application/json
```

### Parameters

| Parameter     | Type   | Description                           |
| ------------- | ------ | ------------------------------------- |
| `packageName` | string | The app's package identifier (in URL) |

### Request Body

```json theme={null}
{
  "permissions": [
    {
      "type": "CAMERA",
      "description": "Take photos to analyze visual content"
    },
    {
      "type": "MICROPHONE",
      "description": "Listen to conversations for transcription"
    },
    {
      "type": "DISPLAY",
      "description": "Show information on glasses display"
    }
  ]
}
```

### Response

Success (200):
Returns the updated app object with new permissions.

Error (400):

```json theme={null}
{
  "error": "Permissions must be an array" // or "Invalid permission type: INVALID_TYPE"
}
```

Error (403):

```json theme={null}
{
  "error": "Unauthorized",
  "message": "You do not have permission to modify this app"
}
```

Error (404):

```json theme={null}
{
  "error": "App not found"
}
```

Error (500):

```json theme={null}
{
  "error": "Internal server error"
}
```

### Implementation

* **File**: `packages/cloud/src/routes/permissions.routes.ts:83-155`
* **Validation**: Validates permission types against `PermissionType` enum from SDK
* **Authorization**: Requires app ownership

### Permission Types

Available permission types (from `@mentra/sdk`):

* `MICROPHONE` - Access to device microphone
* `LOCATION` - Access to device location
* `BACKGROUND_LOCATION` - Access to location in background
* `CALENDAR` - Access to device calendar
* `CAMERA` - Access to device camera
* `NOTIFICATIONS` - Legacy notification permission (backward compatibility)
* `READ_NOTIFICATIONS` - Access to read notifications
* `POST_NOTIFICATIONS` - Access to post notifications
* `ALL` - All available permissions

### Permission Object Structure

Each permission must include:

* `type`: One of the valid `PermissionType` enum values
* `description`: String explaining why the app needs this permission (optional but recommended)

## Error Codes

| Code | Description                                  |
| ---- | -------------------------------------------- |
| 400  | Invalid permissions format or type           |
| 401  | Unauthorized - invalid token                 |
| 403  | Forbidden - no permission to view/modify app |
| 404  | App not found                                |
| 500  | Internal server error                        |

## Notes

* Each permission should include a description explaining its use to users
* Permissions are validated against the SDK's `PermissionType` enum
* Organization context can be provided via `X-Org-Id` header
* Only app owners can modify permissions
* All users can view permissions for published apps
* The endpoint uses MongoDB's `findOneAndUpdate` to ensure atomic updates
* Console logs are present in the code for debugging (lines 44-45, 51)