The API

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

You can download an example Postman project here.

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

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

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

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!

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.

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.

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:

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”.

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.

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:

A successful response to a request contains the following fields:

Here's how an example response looks like:

{
"access_token":"PJIeg5uIs31JBmTGmcUFap6Gv2xhJQs84IqetJeL",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"Sj5267kclpjhrvT0pdcE8mVbYxoZTu3u8flqg5cY"
}

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.

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:

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/

• john and love123 - are the FileRun account's username and password
• FileRun0000000000000000000Mobile - is the the default API client id used by the mobile apps. It is recommended that you add a separate one, specific to your application.
• 0000000000000000NoSecret0000000000000000 - the API client secret
• http://localhost - one of the API configured redirect URLs for the particular API client
• https://demo.filerun.com - the URL of your FileRun installation

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:

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.

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.

Sample output:

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

Request Parameters Reference

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:

{
   "success":true,
   "error":false,
   "data":{
      "meta":{
         "path":"\/ROOT\/HOME",
         "parentPath":"\/ROOT",
         "folderName":"Home Folder",
         "perms":{
            "upload":true,
            "download":"1",
            "alter":true
         }
      },
      "files":[
         {
            "filename":"FileRun_Admin_Guide.pdf",
            "weblink":"http:\/\/demo.filerun.com\/wl\/?id=89M",
            "is_dir":false,
            "nicerFileSize":"123 KB"
         },
         {
            "filename":"FileRun_License_Agreement.pdf",
            "is_dir":false,
            "nicerFileSize":"116 KB"
         },
         {
            "filename":"FileRun_User_Guide.pdf",
            "is_dir":false,
            "nicerFileSize":"195 KB"
         },
         {
            "filename":"Welcome.jpg",
            "is_dir":false,
            "nicerFileSize":"17 KB"
         }
      ]
   }
}

Request Parameters Reference

Request Parameters Reference

For additional details please see this page.

Request Parameters Reference

Request Parameters Reference

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

• neY6uAjKO1KqQh98RZZ5DOgYjIPMuu9duvvHGUiN - is the previously received “access_token”
• your-file.ext - is the path of the file you want to upload from the local computer
• https://demo.filerun.com - is the URL of your FileRun installation
• /ROOT/HOME/existing-folder/my-file.ext - is the remote path where you wish the file to be uploaded. The folder needs to exist and will not be automatically created.

—–

Request Parameters Reference

Request Parameters Reference

Request Parameters Reference

Request Parameters Reference

Request Parameters Reference

Request Parameters Reference

Request Parameters Reference

Request Parameters Reference

Example reply:

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

Request Parameters Reference

Example reply:

{
  "success": true,
  "weblinkid": CtmsT8IWoen3JDZIVbxvR3SH45gvvvxs
}

Request Parameters Reference

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

Request Parameters Reference

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

Request Parameters Reference

Request Parameters Reference

Example response

Example response after successful request:

{
   "success": true,
   "error": false,
   "data":{
      "generated_password": "12345678",
      "uid": "44"
   }
}

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

Example response after failed request:

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

Request Parameters Reference

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

Request Parameters Reference

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.

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

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:

RewriteEngine On
RewriteCond %{HTTP:Authorization} .+
RewriteRule .* - [[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.