The API

Quick start for PHP developers

Authorization

The WebFileShare 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

Important note: To use the WebFileShare API, your webserver needs to be configured with a SSL certificate. The URL of the Web File Share 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

Testing without SSL

Adding the following line inside /customizables/config.php would allow OAuth2 to be enabled even though you do not access the Web File Share installation via HTTPS:

$config['app']['api']['oauth2']['allow_over_http'] = true;

Warning: This disables the entire security of the API. Your Web File Share 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 Web File Share a bit of information about the application. Follow these steps:

Obtain an access token

Before your application can access private data using a Web File Share 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 Web File Share, 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 Web File Share 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 Web File Share 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 Web File Share 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/

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

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

https://www.your-site.com/WebFileShare/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. Web File Share 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 Referer 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/

Parameters:

A successful response to a request contains the following fields:

{
"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 Web File Share 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 Web File Share URL for authentication and providing consent, they usually just prompt the users for their Web File Share username and password.

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

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

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

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

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

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

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

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

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

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