Content-Type: multipart/form-data
// Response (401 Unauthorized):
{ "error": "file.access", "message": "You do not have permission to create files here" }
```
**Anonymous trying to read `/engineering/` files** — No login. Neither rule matches: the admin rule requires a user session, and the department rule requires a logged-in user with a matching department:
```plaintext
// REST API
GET /v1/media/files/10/contents/architecture.pdf
// No auth token
// Response (401 Unauthorized):
{ "error": "file.access", "message": "You do not have permission to access this file" }
```
## Private media files and app bundles
Files that do not have an unconditional public read rule (i.e., `"allow": "all"` for `"read"`) are treated as **private**. This affects how files are included in app bundles:
- **Public files** are included in the app bundle as normal and are available offline
- **Private files** are excluded from the bundle — only metadata (file ID, name, content type) is included
- At runtime, the app must make **authenticated API requests** to access private file contents (e.g., via `Fliplet.Media.Files.get()` or the `/v1/media/files/:id/contents` endpoint)
- Private files are **not available offline** unless your app explicitly fetches and caches them at runtime
This partitioning ensures that secured files are never exposed in the publicly downloadable app bundle.
## Custom security rules
For advanced logic beyond what the standard rule properties support, you can write custom JavaScript security rules. This follows the same model as [custom Data Source security rules](/Data-source-security#custom-security-rules) — the script is evaluated at runtime in a sandboxed environment.
Important: When a rule has a custom script, the script is the sole determinant of access. Standard rule fields like allow and type are ignored — the script runs regardless of login status or operation type. Your script must perform its own identity and operation checks (e.g., if (!user) return { granted: false };). If the script does not return a value (e.g., an unhandled operation type falls through without a return), access is denied by default.
When writing a custom rule, these variables are available in the script context:
- `type` (String) — the operation being attempted: `read`, `create`, `update`, or `delete`
- `user` (Object) — the authenticated user's session data, or `undefined` if not logged in. For data-source passport sessions (e.g., Email Verification, Fliplet Login), this contains the flat column values from the user's row in the authentication data source (e.g., `user.Email`, `user.Role`). For SAML2 sessions, it contains the assertion attributes.
- `file` (Object) — the resource being accessed. This is the plain Sequelize model of either a file or a folder, depending on the operation. See [The `file` object](#the-file-object) for available properties.
- `DataSources` (Function) — server-side library for reading data from other data sources. See [Reading data from other Data Sources](#reading-data-from-other-data-sources).
Script execution has a 3-second timeout. Async operations (like DataSources queries) are supported via await.
Here is an example covering multiple scenarios:
```js
// Check the operation type
if (type === 'read') {
// Any logged-in user can read
if (user) {
return { granted: true };
}
return { granted: false, message: 'You must be logged in to access this file' };
}
if (type === 'create') {
// Only editors can upload
if (user && user.Role === 'Editor') {
return { granted: true };
}
return { granted: false, message: 'Only editors can upload files' };
}
if (type === 'update' || type === 'delete') {
// Only the original uploader can modify or delete.
// file.userId is the Fliplet user ID of who uploaded the file.
// user.id is the authenticated user's Fliplet user ID (not a data source column).
if (user && file && file.userId === user.id) {
return { granted: true };
}
return { granted: false, message: 'You can only modify files you uploaded' };
}
// Deny by default if none of the conditions above matched
return { granted: false };
```
### Granting access
Return `{ granted: true }` to allow access, or `{ granted: false }` to deny. You can include a `message` when denying for debugging purposes (e.g., `{ granted: false, message: 'Only managers can access report files' }`).
Important: You must return an object — bare boolean values (e.g., return true) are not supported and will be treated as a denial. Always use return { granted: true } or return { granted: false }.
### The `file` object
The `file` variable in custom scripts contains the plain Sequelize model of the resource being accessed — either a file or a folder. The available properties depend on the resource type.
**For files:**
```js
{
id: 456,
name: "team-photo.jpg",
contentType: "image/jpeg",
size: [640, 480], // Image dimensions [width, height] — only populated for images
mediaFolderId: 12, // ID of the parent folder
appId: 789,
userId: 42, // ID of the user who uploaded the file
isEncrypted: false,
metadata: {},
accessRules: null, // This file's own rules (if any)
createdAt: "2025-06-15T10:30:00Z",
updatedAt: "2025-06-15T10:30:00Z"
}
```
**For folders** (when the operation targets a folder, e.g., `create` for uploading into a folder):
```js
{
id: 12,
name: "2025",
parentId: 5, // ID of the parent folder
appId: 789,
metadata: {},
accessRules: null,
createdAt: "2025-01-10T08:00:00Z",
updatedAt: "2025-01-10T08:00:00Z"
}
```
Important: The file object does not include related records (folder details, app name, uploader email). To look up related data, use the DataSources library or match on the available IDs (userId, mediaFolderId, appId).
For `create` operations (file upload), `file` contains the metadata available from the upload request (e.g., `name`, `contentType`). Fields like `id` and `createdAt` are not yet available.
### Restrict file types on upload
```js
if (type === 'create') {
var allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
if (file && allowedTypes.indexOf(file.contentType) === -1) {
return { granted: false, message: 'Only JPEG, PNG, and PDF files are allowed' };
}
return { granted: true };
}
// This rule does not grant access to other operation types
```
### Reading data from other Data Sources
Custom rules can query other data sources using the `DataSources` server-side library. The API is identical to [data source custom rules](/Data-source-security#reading-data-from-other-data-sources) — refer to that page for the full `find` and `findOne` reference, supported query operators, and usage examples.
These reads run at **server level** and bypass all security rules on the target data source. Connect using the data source ID (number) or name (string):
```js
if (type === 'create') {
if (!user) {
return { granted: false, message: 'You must be logged in to upload files' };
}
var permission = await DataSources('Permissions').findOne({
where: { Email: user.Email, CanUpload: 'Yes' }
});
if (permission) {
return { granted: true };
}
return { granted: false, message: 'You do not have upload permissions' };
}
```
Use DataSources('Name') (data source name) instead of DataSources(123) (ID) in custom scripts. Data source names are preserved during app clone, so name-based lookups continue to work without manual remapping.
## REST API endpoints
To manage access rules programmatically, see the [Media access rules API](/REST-API/fliplet-media#access-rules) for endpoints to get and set rules on files, folders, and apps.