Authentication and Authorization with the Filerobot API happens via two methods:
- API Secret Keys - they are best for server-to-server upload and interaction with the Filerobot store, for example for migrating large bulks of media assets from another Cloud storage service or uploading large amounts of media assets from your server.
- Security Templates - that are templates for generating Access Keys with limited validity and permissions, adapted to frontend browser uploads.
Both methods support key permissions and allow for granular definition of what each method 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 method you use to upload, manage and retrieve media assets in Filerobot programmatically depends on your use case:
|Use Case||API Secret Key||Security Templates (and 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 360° spin plugin|
|Filerobot Media Asset Widget (FMAW)|
Regardless of which authentication method you use, the API key needs to be included as part of the
X-Filerobot-Key HTTP header in your requests.
1. Using API Secret Keys
API Secret Keys are the easiest way to get started with the Filerobot API. Navigate to Developers > API Secret Keys and click on the Create new key button.
Give a description and 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 Security Templates and 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.
1. Creating an Security Template
Navigate to Developers > 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:
|Restrict IP limitation||
|Key validity||Key validity period|
|Listing limits||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 \ --url 'https://api.filerobot.com/fdocs/key/SECU_3268740E1C82464B9BC350D868F966CB?' \ --header 'Content-Type: application/json'
"hint": "New key created and ready to use",