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 Web File Share login. If you type in the wrong password too many times, the Web File Share user account will get deactivated.
Example
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/
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 Web File Share control panel |
client_secret | The client secret obtained from the Web File Share 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 Web File Share API with the access token
After your application obtains an access token, you can use the token to make calls to the Web File Share 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 /WebFileShare/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 WebFileShare API multiple times for similar operations.
Access tokens have limited lifetimes (around 1 hour). If your application needs access to the Web File Share 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 |
HTTP Method | GET/POST |
Output format | JSON |
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 value | 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 Web File Share icon associated with this type of files | |
details[hasThumb] | array key | No | shows if Web File Share 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:
{ "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" } ] } }
Retrieving metadata
Target URL | /api.php/files/metadata/ |
Required scope | metadata |
HTTP Method | GET/POST |
Output format | JSON |
Request Parameters Reference
Parameter | Type | Default value | Required | Description |
---|---|---|---|---|
path | string | Yes | Examples: /ROOT/HOME/file.ext - retrieves metadata for a file named file.ext available in the Web File Share user's home folder |
Searching files and folders by name
Target URL | /api.php/files/search/ |
Required scope | list |
HTTP Method | GET/POST |
Output format | JSON |
Request Parameters Reference
Parameter | Type | Default value | Required | Description |
---|---|---|---|---|
path | string | Yes | Path relative to the user's home folder. | |
keyword | string | Yes | The keyword to search the file names for. | |
details | array | No | The same as as for the task above. |
Creating folders
Target URL | /api.php/files/createfolder/ |
Required scope | upload |
HTTP Method | POST/GET |
Request Parameters Reference
Parameter | Type | Description |
---|---|---|
path | string | Web File Share 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 |
Output format | JSON |
Request Parameters Reference
Parameter | Type | Description |
---|---|---|
path | string | The Web File Share path of the target file. |
Example
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
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 Web File Share 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 Web File Share path of the file. |
Renaming files or folders
Target URL | /api.php/files/rename/ |
Required scope | modify |
HTTP Method | GET/POST |
Output format | HTTP DOWNLOAD |
Request Parameters Reference
Parameter | Type | Description |
---|---|---|
path | string | |
newName | The new file/folder name. |
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 Web File Share 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 Web File Share 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 Web File Share 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. |
Example reply:
{ "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 } }
Sharing 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 Web File Share path of the folder. |
uid | integer | Yes if no “gid” | ID of Web File Share user to share folder with. |
gid | integer | Yes if no “uid” | ID of Web File Share group to share folder 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 is granted. |
alias | string | No | Specify an alias for the shared folder name. |
Note: If the folder was already shared, the share settings will be updated. No errors will be returned in that case.
Unsharing 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 Web File Share path of the folder. |
uid | integer | Yes if no “gid” | ID of Web File Share user to be removed from the share. |
gid | integer | Yes if no “uid” | ID of Web File Share group to be removed from the share. |
Note that the call will return an error if the folder is not shared with the specified user or group.
Get Web File Share 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 Web File Share 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 |
---|---|---|---|---|
generate_password | boolean | No | Set to 1 to have Web File Share assign a randomly generated password which matches the current password policy settings. | |
create_home_folder | boolean | No | Set to 1 to have Web File Share create the user's home folder if it doesn't exist already. | |
data[username] | string | Yes | The username may not contain special characters, except for underscores, dashes, @, dots and spaces. | |
data[name] | string | Yes | ||
data[password] | string | No | ||
data[two_step_enabled] | boolean | 0 | No | |
data[two_step_secret] | string | No | ||
data[last_pass_change] | date | NULL | No | |
data[owner] | integer | NULL | No | This can be the ID of the parent independent admin user. |
data[registration_date] | date | current date | No | |
data[activated] | boolean | 1 | No | |
data[expiration_date] | date | NULL | No | |
data[require_password_change] | boolean | 0 | No | |
data[email] | string | No | ||
data[receive_notifications] | boolean | 0 | No | |
data[company] | string | No | ||
data[website] | string | No | ||
data[description] | string | No | ||
data[logo_url] | string | No | ||
perms[role] | integer | NULL | No | |
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_metaperms] | 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 | Yes | 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. | |
perms[space_quota_max] | integer | 0 | No | |
perms[space_quota_current] | integer | 0 | No | |
perms[traffic_quota_max] | integer | 0 | No | |
perms[traffic_quota_current] | integer | 0 | No | |
perms[readonly] | boolean | 0 | No | |
perms[upload] | boolean | 1 | No | |
perms[download] | boolean | 1 | No | |
perms[download_folders] | boolean | 1 | No | |
perms[read_comments] | boolean | 0 | No | |
perms[write_comments] | boolean | 0 | No | |
perms[email] | boolean | 0 | No | |
perms[weblink] | boolean | 0 | No | |
perms[share] | boolean | 0 | No | |
perms[btsync] | boolean | 0 | No | |
perms[metaperms] | boolean | 0 | No | |
perms[file_history] | boolean | 0 | No | |
perms[users_may_see] | string | -ALL- | No | |
perms[change_pass] | 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:
{ "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 Web File Share.
Example response after failed request:
{ "success": false, "error": "The value of data[username] needs to be unique in the database", "code": "username_in_use" }
Modify Web File Share 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 |
Delete Web File Share 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.
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:
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.