Authentication and Authorization with the Filerobot API happens via two types of keys:
- API Secret Keys
- API Access Keys, managed by Security Templates enabling rate-limiting and access restrictions. These keys are prefixed by SASS_
Both type of keys support key Permissions and allow for granular definition of what each key can do (upload, list, search, create directory, delete, ...). However, only API Secret Keys can be company-wide keys and allow the interaction with multiple Filerobot projects. Read here to learn more about what is a Filerobot project.
The type of key you use to upload, manage and retrieve media assets in Filerobot programmatically depends on your use case:
|Use Case||API Secret Key||API Access Key|
|Upload, manage and retrieve media assets from backend servers to Filerobot||Recommended as the API Secret Key will never be exposed. Secret keys can be company-wide and authenticate across multiple projects.||
Recommended if you want to apply API rate-limiting and have IP-based restrictions.
|Filerobot Uploader Widget integrated into a frontend application||Not recommended as the key is exposed in your frontend code to end users.||
Recommended to prevent the key from being compromised and used outside of the Widget.
|Filerobot Image Editor integrated into a frontend application|
|Filerobot / Cloudimage 360° spin plugin|
1. Using API Secret Keys
API Secret Keys are the easiest way to get started with the Filerobot API. Navigate to Settings > Developer > API Secret Keys and click on the Create new key button.
Give the a description and select for which projects the key should have Permissions on. You can also select all projects associated to your company.
Finally, select the Permissions the API Secret Key will have. You can choose between multiple permissions as described in the Filerobot documentation.
Once the API Secret Key is saved, you can review/edit its Permissions, rename or revoke it from the list:
2. Using API Access Keys
API Access Keys are based on API Secret Keys but add additional restrictions like rate-limiting, max file size upload, IP-whitelisting, etc ... for the API client using them to authenticate against the Filerobot API. They are meant to be used in conjunction with the Filerobot Widgets and Plugins, mainly on frontend applications or on highly-sensitive backend applications.
First, a Security Template must be created in order to specify the API Access Keys' restrictions and then an API Access Key must be requested over API.
1. Creating an Security Template
Navigate to Settings > Developer > Security Templates and click on the Create new template button to create a new Security Template.
4 categories of limits are available:
rate-limiting for uploads:
|Key validity||Key validity period|
|Listing||Folder scope for listing / search|
Once saved, a unique Security Template identifier is generated and available for use:
The Security Template identifier is required in order to request API Access Keys via the API described in the next section.
2. Requesting API Access Keys
API Access Keys should be requested before an API call to the Filerobot API is done from a server in a backend application or a Filerobot Widget or Plugin is instantiated on a frontend application. Refer to each Widget or Plugin documentation below to understand where the API Access Key should be configured for the Widget or Plugin to be able to authenticate against the Filerobot API and upload / manage / retrieve asset from your Digital Asset Management:
On a side note, these plugins are all Open Source, so do not hesitate to contribute in order to help us making them the best Digital Asset Management Widgets and Plugins.
To request an API Access Key, use the GET /key API documented here. An example of a cURL request / response is given below.
curl --request GET \
--header 'Content-Type: application/json' \
"key": "SASS__v1.05__kTM6AXCvlmLlJ3b0NncpFmLpBXYu0GdkFWczVnZboDZJoyLzR3Y1R2byB3LbojcpR \
"hint": "New key created and ready to use"