API Access should be used for configuring the Filerobot widgets and plugins: Uploader Widget, Image Editor, 360° Spin or any other custom frontend implementation requiring to communicate with the Filerobot API. For server to Filerobot communication, we recommend the usage of API Secret Keys.
API Access Keys are temporary keys with configurable permissions and restrictions to be used in frontend browser interactions with the Filerobot API. They should be used to instantiate the Filerobot widgets and plugins in your frontend application as filerobotUploadKey configuration parameter.
2 are required in order to generate API Access Keys.
1. Create a Security Template
Security Templates are a set of permissions and restrictions that will be applied to each Access Key requested for using the Filerobot widgets and plugins.
To create a Security Template, login to your Filerobot Admin Console and navigate to Settings > Developer > Security Templates. Create a new template:
You can define following permissions and restrictions for various actions:
permissions
permissions permissions on file operations (list, search, ...) granted to the key.
| Permission name | Description |
|---|---|
| OBJECTS_LIST | List files |
| OBJECTS_FETCH | Fetch/Access file |
| FILE_UPLOAD | Upload file |
| FILE_RENAME | Rename file |
| FILE_MOVE | Move file |
| FILE_META_CHANGE | Create file metadata |
| FILE_DELETE | Delete file |
| DIR_CREATE | Create directory |
| DIR_RENAME | Rename directory |
| DIR_MOV | Move directory |
| DIR_META_CHANGE | Create directory metadata |
| DIR_DELETE | Delete directory |
| CONFIG_CHANGE | Change storage container configuration |
| CONFIG_LIST | List storage container configuration |
upload
upload sets limits on the /upload API
| Parameter | Description | Default |
|---|---|---|
| limit_per_min | maximum number of uploads per minute with the key | unlimited |
| max | maximum number of uploads allowed with the key | unlimited |
| limit_per_ip_source | Maximum number of uploads allowed by IP by the key | unlimited |
| dir_scope | Directories where the key is allowed to upload. If you want to allow all subdirectories of /folder, set the value to /folder/* | all directories |
| max_file_size | Maximum upload size in bytes | 500 MB |
restrictions
restrictions restricts API calls based on IP address ranges and | or countries
| Parameter | Description | Default |
|---|---|---|
| whitelist_ip_ranges | Allowed IP ranges for using the key from | 0.0.0.0 format accepted: 8.8.8.8, 255.240.0.0/12, ... |
| whitelist_countries | Allowed countries for using the key from. Provide the code ISO of the country |
all countries The IP are converted to country thanks to GeoLite2 |
key_validity
key_validity allows to set validity period of key, for example to match the user's session length in your authenticated application
| Parameter | Description | Default |
|---|---|---|
| expiration_duration | time in second before the key expires | 1200 s (20 minutes) |
listing
listing sets limit on all the API except /upload
| Parameter | Description | Default |
|---|---|---|
| dir_scope | directories from where it's allowed to list file. If you want to allow all subdirectories of /folder you need to set the value to /folder/* | /* (all directories) |
| max | maximum of call to the API | Unlimited |
2. Requesting an Access Key
In order to instantiate the Filerobot Uploader widget or Filerobot Image Editor widget, you will for most use cases need to specify the filerobotUploadKey parameter for the widgets to interact with your Filerobot asset storage. When the page embedding the widget is loaded, make an API call in order to request an Access Key based on the Security Template previously created.
API Access Keys are generated by calling:
Response
{
"status": "success",
"key": "SASS__v1.05__kTM6AXCvlmLlJ3b0NncpFmLpBXYu0GdkFWczVnZboDZJoyLzR3Y1R2byB3LbojcpRGbJADM2MjOldWYJoyLzR3Y1R2byB3LbojcpRWdJADMwEjOtBXb1lwN3gjM0MzNwYTM6Q3c__9df8ffb9fe",
"hint": "New key created and ready to use",
"debug": null
}You can use the returned key as the filerobotUploadKey parameter in the Filerobot widget or plugin configuration.