Luminous Drive (the product formerly called File Cabinet) has an External API, so your own scripts and integrations can work with Drive files and folders. This article covers how to connect and what an API token can and can't reach.
Before you start
- Drive must be turned on for your account. If it isn't, every Drive API call returns a "Not found" (404) response. Contact Luminous support if you expect Drive to be on and see 404s.
- You need an API token. Create one under Admin → Settings → API Tokens. Send it on every request in an
Authorization: Bearer <your-api-token>header. See the article linked at the end for the full steps. - The base path for all Drive calls is
/external/api/v1/file-cabinet.
A token acts as the user who owns it
Every token belongs to a Luminous user, and Drive checks that user's role permissions on each call. There are two levels:
| Permission on the token's user | What it allows through the API |
|---|---|
Read (fileCabinet.read) | Browse and look things up: folders, files, file details, downloads, versions, tags, the activity trail, and which records a file is attached to. |
Write (fileCabinet.write) | Everything that changes something: upload, create folders, rename and move, set tags, attach files to records, apply an image to a SKU, turn on a public image URL, move items to Trash, restore and delete forever. |
A call without the needed permission returns a 403 ("You do not have permission to use Drive this way"). Without a valid token it returns a 401.
Tag renaming and deletion also need the Manage Drive permission on the token's user, as they do in the app. Anyone with write access can create tags.
What an integration can do
Browse and search
- Get the folder tree and open a folder.
- Search and list files, and get a file's details.
- Download a file and list its versions.
Upload and organize
- Upload a file directly, or start an upload and then complete it.
- Upload a new version of an existing file by passing that file instead of a folder.
- Create folders.
- Rename or move files and folders. For files you can also change the restricted setting and the expiry date.
Tags
- List, create, rename and delete tags.
- Set the tags on any file or folder.
Records
- Attach files to a record (up to 100 files per request), list a record's attached files, and remove an attachment.
- See which records a file is attached to.
- Apply an image to a SKU.
- Turn on a public image URL for a file.
Activity
- Read the activity trail of a file.
Trash
- Delete a file or folder (it moves to Trash), list Trash, restore items, or delete them forever.
What API tokens can NOT reach
API tokens only see the shared drive. This holds even if the token's owner can open more in the app.
- Restricted folders and files are off limits, and so is everything inside a restricted folder.
- My Files is off limits. That includes the token owner's own My Files and anyone else's.
- Trash follows the same rule. A token can't reach restricted or private items, including those inside a trashed folder.
- Record folders follow record permissions. The folders Luminous fills from your records (Sales Orders and so on) stay hidden if the token's user lacks permission to read that record type.
Items a token can't see return "not found" rather than "forbidden", so their existence isn't revealed.
Activity is labelled as an API call
Every action a token takes is recorded in the file's activity trail and marked as coming from an API token. You can tell integration activity apart from what people do in the app.
Tips
- Use one token per integration, so you can revoke one without affecting the others.
- Give the token's user only the Drive permissions the integration needs. A read-only integration only needs View Drive.
Related
For creating tokens and the required headers, see "How does authentication work for the Luminous External API, and what headers are required?"