The API

Quick start for PHP developers

  1. Read the #Authorization section below to understand the requirements.
  2. Follow "Adding a new client application"
  3. Download and use the FileRun PHP API Client library: https://github.com/filerun/api-client

Quick start

You can download an example Postman project here.

Import it and start testing with our demo: https://filerun.com/demo

Swagger/OpenAPI basic specification file: https://app.swaggerhub.com/apis-docs/filerun/api/1.0.0

Enabling the API

To enable the API:

  1. Sign-in to your FileRun installation, as superuser
  2. Open the control panel
  3. Browse to API
  4. Click the Enable API checkbox and click Save changes

Important note: To use the FileRun API, your webserver needs to be configured with an SSL certificate. The URL of the FileRun installation needs to start with HTTPS. Unsecured HTTP connections will be refused, as it represents a serious security vulnerability.

Get a free SSL certificate here: https://letsencrypt.org

Authorization

The FileRun API uses the OAuth 2.0 protocol for authentication and authorization.

If you are new to OAuth2, here you can find a good article about it here: https://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified

Testing without SSL

You can enable access via HTTP instead of HTTPS, from the FileRun control panel, under API.

Warning: This disables the entire security of the API. Your FileRun users private information will be at risk. Do not use it for production!

Adding a new client application

Before you can start using OAuth2 with your application, you'll need to tell FileRun a bit of information about the application. Follow these steps:

  1. Login to FileRun as superuser.
  2. Open the control panel and navigate to API > Clients.
  3. Click "Add" and fill in the form.
  4. FileRun will generate a "client id" and a "client secret". Make a note of these two, as you will need to set them in your application.

Obtain an access token

Before your application can access private data using a FileRun API, it must obtain an access token that grants access to that API. A single access token can grant varying degrees of access to multiple APIs. A variable parameter called "scope" controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the "scope" parameter.

There are several ways to make this request, and they vary based on the type of application you are building. For example, a web-based application might request an access token using a browser redirect to FileRun, while an application installed on a device that has no browser uses web service requests.

Some requests require an authentication step where the user logs in with their FileRun account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called *user consent*.

If the user grants the permission, the FileRun Authorization Server sends your application an access token (or an authorization code that your application can use to obtain an access token). If the user does not grant the permission, the server returns an error.

The authorization sequence begins when your application redirects a browser to a specific FileRun URL; the URL includes query parameters that indicate the type of access being requested.

For web applications

This method is called in OAuth 2.0 terms "the authorization code flow".

Authentication Endpoint URL: /oauth2/authorize/ (HTTP GET)

The set of query string parameters supported by the FileRun Authorization Server for web server applications are:

Parameter Value Description
response_type code Determines whether the FileRun OAuth 2.0 endpoint returns an authorization code. Web server applications should use code.
client_id The "client id" you obtain from the FileRun control panel Identifies the client that is making the request. The value passed in this parameter must exactly match the value shown in the FileRun Control Panel
redirect_uri One of the "redirect uri" values listed for this application Determines where the response is sent. The value of this parameter must exactly match one of the values listed for your application in the FileRun control panel, including the http or https scheme, case, and trailing '/').
scope Space-delimited set of permissions that the application requests. Identifies the FileRun API access type that your application is requesting.
state Any string Provides any state that might be useful to your application upon receipt of the response. The FileRun Authorization Server roundtrips this parameter, so your application receives the same value it sent. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response.

An example request URL is shown below, with line breaks for readability.

GET https://www.your-site.com/filerun/oauth2/authorize/?
  scope=email%20profile&
  state=SOME-RANDOM-DATA&
  redirect_uri=https%3A%2F%2Fwww.your-app.com%2Fdo-something-with-the-code&
  response_type=code&
  client_id=f9c6f82cb3e872a20e6a310f33a9c450

You web application will be redirecting the users to a similar URL. FileRun then handles the user authentication and consent. The result is an authorization code, which your application can exchange for an "access token" and a "refresh token".

Handling the response

The response will be sent to the "redirect_uri" as specified in the request URL. If the user approves the access request, then the response contains an authorization code and the state parameter (if included in the request). If the user does not approve the request, the response contains an error message.

Important: if your response endpoint renders an HTML page, any resources on that page will be able to see the authorization code in the URL. Scripts can read the URL directly, and all resources may be sent the URL in the Referrer HTTP header. Carefully consider if you want to send authorization credentials to all resources on that page (especially third-party scripts such as social plugins and analytics). To avoid this issue, we recommend that the server first handle the request, then redirect to another URL that doesn't include the response parameters.

Getting the access token

After your web application receives the authorization code, it should exchange it for an access token and a refresh token, by making an HTTP POST request to the following URL:

Token Endpoint URL: /oauth2/token/ (HTTP POST)

Parameters:

Parameter Description
code The authorization code returned from the initial request.
client_id The "client id" obtained from the FileRun control panel
client_secret The client secret obtained from the FileRun control panel.
redirect_uri One of the redirect URIs listed for this project in the
grant_type As defined in the OAuth 2.0 specification, this field must contain a value of "authorization_code".

A successful response to a request contains the following fields:

Parameter Description
access_token The token that needs to be sent to the FileRun API for a regular request.
refresh_token A token that may be used to obtain a new access token. Refresh tokens expire in 30 days.
expires_in The remaining lifetime of the access token. Access tokens expire in 60 minutes.
token_type Identifies the type of token returned. At this time, this field will always have the value Bearer.

Here's how an example response looks like:

 1{
 2"access_token":"PJIeg5uIs31JBmTGmcUFap6Gv2xhJQs84IqetJeL",
 3"token_type":"Bearer",
 4"expires_in":3600,
 5"refresh_token":"Sj5267kclpjhrvT0pdcE8mVbYxoZTu3u8flqg5cY"
 6}

The application should store the refresh token for future use and use the access token to access the FileRun API. Once the access token expires, the application uses the refresh token to obtain a new one.

For installed applications

This method is called in OAuth 2.0 terms the "resource owner credentials flow". It is also known as the "password" flow.

Desktop and mobile application, if they cannot redirect the user to the FileRun URL for authentication and providing consent, they usually just prompt the users for their FileRun username and password.

The process requires just a direct HTTP POST call to the token endpoint (/oauth2/token/), with the following parameters:

Parameter Description
username The FileRun user account username.
password The FileRun user account password.
scope Space-delimited set of permissions that the application requests. Identifies the FileRun API access type that your application is requesting. Each API method that your application will be using requires a certain scope. See that further down in the documentation.
client_id The "client id" obtained from the FileRun control panel
client_secret The client secret obtained from the FileRun control panel.
redirect_uri One of the redirect URIs listed for this application inside the FileRun control panel.
grant_type As defined in the OAuth 2.0 specification, this field must contain a value of "password".

Please see the above section Getting the access token for handling the response.

Note: This type of authorization is protected against brute force attacks, just as the regular FileRun login. If you type in the wrong password too many times, the FileRun user account will get deactivated.

Example

curl -X POST -d "username=john&password=love123&scope=upload&client_id=FileRun0000000000000000000Mobile&client_secret=0000000000000000NoSecret0000000000000000&redirect_uri=http://localhost&grant_type=password" https://demo.filerun.com/oauth2/token/

Refreshing the access token

As access tokens expire, you will need to get fresh one once in a while. You do that by making a HTTP call to the following URL:

Refresh Token Endpoint URL: /oauth2/token/

Parameters:

Parameter Description
client_id The "client id" obtained from the FileRun control panel
client_secret The client secret obtained from the FileRun control panel.
grant_type As defined in the OAuth 2.0 specification, this field must contain a value of "refresh_token".
refresh_token The refresh token you have received along with the access token.

A successful response to a request will be identical to the response you receive when you are requesting an initial access token (See Getting the access token).

Note: Save refresh tokens in secure long-term storage and continue to use them as long as they remain valid.

Calling the FileRun API with the access token

After your application obtains an access token, you can use the token to make calls to the FileRun API on behalf of a given user account. To do this, include the access token in a request to the API by including the "Authorization: Bearer" HTTP header.

Example:

GET /filerun/api.php/account/info HTTP/1.1
Authorization: Bearer 8vDeNtzJ8Nf1P0fH1YsvIubOMGttXpqOmupl3oD1
Host: www.your-site.com

Where 8vDeNtzJ8Nf1P0fH1YsvIubOMGttXpqOmupl3oD1 is the access token received on the previous step.

For most API calls, the server reply will contain a JSON object in the response body. Successful requests will have a property named "success" with the boolean value "true". For failed requests, the "success" value will be set to "false" and the "error" property will be populated with an textual description of the problem. For tasks which are supposed to provide information, such as attaching a web link to a file, the property "data" will be populated if the operation was successful.

Access tokens are valid only for the set of operations and resources described in the scope of the token request. For example, if an access token is issued for the purpose of listing directory contents (scope=list), it cannot be used for accessing the user's profile information (scope=profile). You can, however, send that access token to the FileRun API multiple times for similar operations.

Access tokens have limited lifetimes (around 1 hour). If your application needs access to the FileRun API beyond the lifetime of a single access token, it can use the obtained refresh token to get a new access token.

API methods

Getting user account information
Target URL /api.php/account/info
Required scope profile
Optional additional scope email
HTTP Method GET/POST
Output format JSON

Sample output:

{
 "id": "123",
 "activated":"1",
 "username": "john",
 "name": "John",
 "name2": "Doe",
 "email": "johndoe@email.com"
}

Retrieving lists of files and folders
Target URL /api.php/files/browse/
Required scope list
HTTP Method GET/POST
Output format JSON

Request Parameters Reference

Parameter Type Default Required Description
path string Yes Examples:
/ROOT - shows a list with items like "My Files", "Shared with me", "Starred" (the list can change in the future)
/ - same as above
/ROOT/HOME - items located inside the users home folder (My Files)
/STARRED - starred items
/PHOTOS - latest photos
/MUSIC - latest audio files
/SHARES - items shared by the user
/LINKS - items shared through web links
/ROOT/SHARED - users with shares or folders shared anonymously by other users
/ROOT/123 - lists folders shared by user with ID 123.
/ROOT/123/456 - list items inside the share with ID 456 owned by user with ID 123.
itemType string Yes Choose type of items to list. Possible values:
any - lists both files and folders
files - lists only files
folders - lists only folders
recursive boolean false No List items from all the subfolders.
details array No Allows you to choose what information should be retrieved for each file.
details[uuid] array key No unique id which can be used for referencing the file or folder
details[mdate] array key No modified date
details[mdateHuman] array key No modified date in a friendly format
details[cdate] array key No creation date
details[hasWebLink] array key No if file has weblink attached to it or not
details[weblink] array key No retrieve weblink URL
details[weblink-full] array key No retrieve full weblink details
details[description] array key No file type description
details[ext] array key No file extension
details[type] array key No type of file (defined inside system/data/filetypes.php)
details[icon] array key No filename of the FileRun icon associated with this type of files
details[hasThumb] array key No shows if FileRun can generate a thumbnail for the file
details[fileSize] array key No includes the file size in bytes
details[nicerFileSize] array key No includes formatted file size
details[commentsCount] array key No includes number of attached user comments
details[label] array key No includes files labels
details[isLocked] array key No shows if file is locked
details[version] array key No includes current file version
details[isShared] array key No shows if folder is currently shared

Example

Listing only files from the users home folder, retrieving information about their attached weblinks and also including a formatted filesize:

 path=/ROOT/HOME
 itemType=files
 details[[]]=nicerFileSize
 details[[]]=weblink

path=/ROOT/HOME - the users home folder

itemType=files - listing only files

details[]=nicerFileSize - including a formatted filesize

details[]=weblink - including the URL, if a weblink is attached

Expected output:

 1{
 2   "success":true,
 3   "error":false,
 4   "data":{
 5      "meta":{
 6         "path":"\/ROOT\/HOME",
 7         "parentPath":"\/ROOT",
 8         "folderName":"Home Folder",
 9         "perms":{
10            "upload":true,
11            "download":"1",
12            "alter":true
13         }
14      },
15      "files":[
16         {
17            "filename":"FileRun_Admin_Guide.pdf",
18            "weblink":"http:\/\/demo.filerun.com\/wl\/?id=89M",
19            "is_dir":false,
20            "nicerFileSize":"123 KB"
21         },
22         {
23            "filename":"FileRun_License_Agreement.pdf",
24            "is_dir":false,
25            "nicerFileSize":"116 KB"
26         },
27         {
28            "filename":"FileRun_User_Guide.pdf",
29            "is_dir":false,
30            "nicerFileSize":"195 KB"
31         },
32         {
33            "filename":"Welcome.jpg",
34            "is_dir":false,
35            "nicerFileSize":"17 KB"
36         }
37      ]
38   }
39}

Retrieving metadata
Target URL /api.php/files/metadata/
Required scope metadata
HTTP Method GET/POST
Output format JSON

Request Parameters Reference

Parameter Type Required Description
path string Yes Examples: /ROOT/HOME/file.ext - retrieves metadata for a file named file.ext available in the FileRun user's home folder

Searching files and folders
Target URL /api.php/files/search/
Required scope list
HTTP Method POST
Output format JSON

Request Parameters Reference

Parameter Type Required Description
path string Yes /ROOT/HOME - search inside the user's home folder (My Files)
/ROOT/123/456 - search inside the share with ID 456 owned by user with ID 123.| |filename|string|No| | |metatype|integer|No|ID of metadata file type. Get this from the FileRun control panel.| |meta|array|No|The keys are metadata fields IDs, you can find them in FileRun's control panel. The key can also be any of the following strings: tag, rating, label, comment, or the character - for searching any field. The values are array of keywords to be searched for.
contents string No Keyword to search files contents. Cannot be combined with any other search criteria.
details array No Same as here.

For additional details please see this page.

Creating folders
Target URL /api.php/files/createfolder/
Required scope upload
HTTP Method POST/GET

Request Parameters Reference

Parameter Type Description
path string FileRun path of the new folder's parent.
name string Name of the new folder.

Uploading files
Target URL /api.php/files/upload/
Required scope upload
HTTP Method PUT/POST
Output format JSON

Request Parameters Reference

Parameter Type Description
path string The FileRun path of the target file.
filePath string To be used instead of path when you wish a folder structure to be automatically created.

For HTTP POST upload, the request's Content-Type should be multipart/form-data with the file part looking like this: Content-Disposition: form-data; name=β€œfile”; filename=β€œignored.ext”. Note that the filename is taken from the path or filePath parameter, not the multipart data.

Example

curl -X PUT --header "Authorization: Bearer neY6uAjKO1KqQh98RZZ5DOgYjIPMuu9duvvHGUiN" -T your-file.ext https://demo.filerun.com/api.php/files/upload/?path=/ROOT/HOME/existing-folder/my-file.ext

Downloading files
Target URL /api.php/files/download/
Required scope download
HTTP Method GET/POST
Output format HTTP DOWNLOAD

Request Parameters Reference

Parameter Type Description
path string The FileRun path of the file.

Downloading thumbnails
Target URL /api.php/files/thumbnail/
Required scope download
HTTP Method GET/POST
Output format HTTP DOWNLOAD

Request Parameters Reference

Parameter Type Description
path string The FileRun path of the file.

Renaming files or folders
Target URL /api.php/files/rename/
Required scope modify
HTTP Method GET/POST
Output format JSON

Request Parameters Reference

Parameter Type Description
path string The FileRun path of the file/folder.
newName string The new name.

Moving files or folders
Target URL /api.php/files/move/
Required scope download + upload
HTTP Method POST
Output format JSON

Request Parameters Reference

Parameter Type Description
path string The FileRun path of the file/folder.
moveTo string The FileRun path of the destination folder.

Extracting archives
Target URL /api.php/files/extract/
Required scope modify
HTTP Method POST
Output format JSON

Request Parameters Reference

Parameter Type Description
path string The FileRun path of the archive file.
extractTo string The FileRun path of the destination folder.

Deleting files or folders
Target URL /api.php/files/delete/
Required scope delete
HTTP Method GET/POST
Output format JSON

Request Parameters Reference

Parameter Type Description
path string The FileRun path of the target file.
permanent boolean (1/0) Either the file should be permanently removed, instead of just moved to the trash folder.

Starring files or folders
Target URL (add) /api.php/files/star/
Target URL (remove) /api.php/files/unstar/
Required scope modify
HTTP Method GET/POST
Output format JSON

Request Parameters Reference

Parameter Type Description
path string The FileRun path of the target file/folder.

Create web links on files and folders
Target URL /api.php/files/weblink/
Required scope weblink
HTTP Method GET/POST
Output format JSON

Request Parameters Reference

Parameter Type Description
path string The FileRun path of the target file/folder.
singleDownload boolean Returns a link which is valid for a single download. This does not affect web links the user might have previously created on the file/folder.
temporary boolean Returns a link which is valid for 15 minutes. This does not affect web links the user might have previously created on the file/folder.
password string
expiry datetime MySQL datetime format (Y-m-d H:i:s)
download_limit integer
allow_uploads boolean Valid for folders. Enables a file request.
allow_downloads boolean Valid for folders. Enables a file request with ability of downloading existing files.
force_save bool Prompts the browser to save the file instead of opening it.
show_comments boolean
show_comments_names boolean
show_metadata boolean
notify boolean
download_terms string
require_login boolean Only logged in FileRun users will be able to access the link.

Example reply:

 1{
 2  "success": true,
 3  "error": false,
 4  "data": {
 5    "status": "created", //can also return "existing"
 6    "url": "http:\/\/www.yoursite.com\/filerun\/wl\/?id=CtmsT8IWoen3JDZIVbxvR3SH45gvvvxs",
 7    "isdir": false //or true if you are linking a folder
 8  }
 9}

Removing web links
Target URL /api.php/files/unweblink/
Required scope weblink
HTTP Method GET/POST
Output format JSON

Request Parameters Reference

Parameter Type Description
path string The FileRun path of the target file/folder.

Example reply:

 1{
 2  "success": true,
 3  "weblinkid": CtmsT8IWoen3JDZIVbxvR3SH45gvvvxs
 4}

Sharing files and folders
Target URL /api.php/files/share/
Required scope share
HTTP Method GET/POST
Output format JSON

Request Parameters Reference

Parameter Type Required Description
path string Yes The FileRun path of the file or the folder.
uid integer Yes if no "gid" or "name" + "email" ID of FileRun user to share folder with.
gid integer Yes if no "uid" or "name" + "email" ID of FileRun group to share folder with.
name string Yes if no "gid" or "uid" Name of guest user to add and share with.
email string Yes if no "gid" or "uid" E-mail address of guest user to add and share with.
anonymous boolean No Specify if folder is to be shared anonymously.
upload boolean No Specify if upload permission is granted.
download boolean No Specify if download permission is granted.
comment boolean No Specify if the permission to post comments is granted.
read_comments boolean No Specify if the permission to read comments is granted.
alter boolean No Specify if the permission to make file changes is granted.
share boolean No Specify if the permission to share files using web links or via e-mail is granted.
alias string No Specify an alias for the shared folder name. Does not apply to sharing files.

Note: If the file or folder was already shared, the share settings will be updated. No errors will be returned in that case.

Unsharing files and folders
Target URL /api.php/files/unshare/
Required scope share
HTTP Method GET/POST
Output format JSON

Request Parameters Reference

Parameter Type Required Description
path string Yes The FileRun path of the file or the folder.
uid integer Yes if no "gid" ID of FileRun user to be removed from the share.
gid integer Yes if no "uid" ID of FileRun group to be removed from the share.

Note that the call will return an error if the file or folder was not shared with the specified user or group.

Get FileRun user account information
Target URL /api.php/admin-users/info
Required scope admin
HTTP Method POST
Output format JSON

Request Parameters Reference

Parameter Type Required Description
UID integer Yes, if uname not provided User ID
uname string Yes, if UID not provided Username

Add FileRun user accounts
Target URL /api.php/admin-users/add
Required scope admin
HTTP Method POST
Output format JSON

Request Parameters Reference
Parameter Type Default value Required Description
data[username] string Yes The username may not contain special characters, except for underscores, dashes, @, dots and spaces.
data[name] string Yes
data[last_name] string No
data[password] string No
generate_password boolean No Set to 1 to have FileRun assign a randomly generated password which matches the current password policy settings.
data[two_step_enabled] boolean 0 No
data[owner] integer NULL No This can be the ID of the parent independent admin user.
data[activated] boolean 1 No
data[expiration_date] MySQL datetime NULL No Example: 2024-01-31 00:00:00
data[require_password_change] boolean 0 No
data[email] string No
data[receive_notifications] boolean 0 No
data[phone] string No
data[company] string No
data[website] string No
data[description] string No
data[logo_url] string No
perms[role] integer NULL No ID of role. If defined, the homefolder is automatically set.
perms[admin_type] string NULL No Possible values: simple, indep
perms[admin_users] boolean 0 No
perms[admin_roles] boolean 0 No
perms[admin_notifications] boolean 0 No
perms[admin_logs] boolean 0 No
perms[admin_metadata] boolean 0 No
perms[admin_over] mixed No Set to "-ALL-" if the user is an admin who can manage all other users
perms[admin_max_users] boolean 0 No
perms[admin_homefolder_template] string No
perms[homefolder] string No The is an absolute path to a folder existing in the server's file system. Always use forward slash as a path separator, including on Windows servers.
create_home_folder boolean No Set to 1 to have FileRun create the user's home folder if it doesn't exist already.
perms[space_quota_max] integer 0 No
perms[readonly] boolean 0 No
perms[upload] boolean 1 No
perms[upload_max_size] integer 0 No
perms[upload_limit_types] string No Comma delimited list of file extensions
perms[download] boolean 1 No
perms[download_folders] boolean 1 No
perms[read_comments] boolean 1 No
perms[write_comments] boolean 1 No
perms[email] boolean 1 No
perms[weblink] boolean 1 No
perms[share] boolean 1 No
perms[share_guests] boolean 1 No
perms[metadata] boolean 1 No
perms[file_history] boolean 1 No
perms[users_may_see] string -ALL- No
perms[change_pass] boolean 1 No
perms[edit_profile] boolean 1 No
groups array No A list of group names. If groups with the specified names are not found, are automatically created.

Example response

Example response after successful request:

 1{
 2   "success": true,
 3   "error": false,
 4   "data":{
 5      "generated_password": "12345678",
 6      "uid": "44"
 7   }
 8}

Where "44" is the ID of the newly created user account and "12345678" is the password generated by FileRun.

Example response after failed request:

 1{
 2    "success": false,
 3    "error": "The value of data[username] needs to be unique in the database",
 4    "code": "username_in_use"
 5}

Modify FileRun user accounts
Target URL /api.php/admin-users/edit
Required scope admin
HTTP Method POST
Output format JSON

Request Parameters Reference

Besides the parameters described higher, for adding user accounts, this API method uses also the following:

Parameter Type Required Description
UID integer Yes The user ID
generate_password boolean No Set this to generate a new password. The plain text generated password will be included in the response.

Delete FileRun user accounts
Target URL /api.php/admin-users/delete
Required scope admin
HTTP Method POST
Output format JSON

Request Parameters Reference

Parameter Type Required Description
UIDS array Yes Array of user ID integers
deleteHomeFolder boolean No If included, this will cause the user(s) home folders to also be deleted.

Revoking app authorization (for users)

Users can see the authorizations made for the various apps, inside the "Account Settings" and can revoke them from the same location at any time.

Sandbox: Test your software

Feel free to use our online demo for testing your application: https://filerun.com/demo

Here's something to help you with this process:https://app.swaggerhub.com/apis-docs/filerun/api/1.0.0

Troubleshooting

"Check the "access_token" parameter"

If you cannot get past the error "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access_token" parameter.", although you have checked and your HTTP request includes the "Authorization" header with a valid "Bearer" token, perhaps PHP doesn't get the variable $_SERVER['HTTP_AUTHORIZATION'] populated. In which case, if you are running Apache, make sure you have the following code inside the .htaccess file:

 1RewriteEngine On
 2RewriteCond %{HTTP:Authorization} .+
 3RewriteRule .* - [[E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]]

If you are using a virtual host, make sure the above is inside the Virtualhost tag, not in Directory tag.