Afi Backup provides Public API that can be utilised to manage and monitor Afi accounts in an automated way. Typical use-cases for Afi Public API include automated resource archiving as well as backup and account status monitoring.
To grant and manage the access to the Public API, Afi uses a concept of an App. Each App is associated with a set of permissions that define the actions which can be performed on behalf of the application via Public API and API keys which are used for authentication when accessing the Public API. This article discusses application creation and management matters, the API reference and how-to guides for the popular use-cases can be found at API Documentation.
Application types
Afi support two types of the Apps - Public and Private, the main difference between these types is that Private Apps can be used only inside a single Afi account and Public Apps can access multiple Afi accounts that have granted the access to the App by installing it. Generally, one should use Private Apps to build their own custom integrations. Public Apps are recommended for partners who want to build the integration which will be potentially beneficial for a number of Afi customers and, thus, will be visible for all Afi clients and available for the installation in another accounts. Public Apps need to undergo verification by Afi Team before being listed publicly and have strict requirements regarding App branding and description.
Application permissions
Right now, Apps can request two types of permissions:
- read access to the account configuration and tasks (this set of roles allows to view account details, account and resources settings, list of resources inside the account, backup task statuses and reporting data);
- write access to the account configuration and tasks(this set of roles allows to modify account and resources settings and trigger backup tasks).
Need to mention that these permissions don't allow the access to the actual backup data, i.e. while the App can manage the backup jobs or access tenant settings, the backup data remains confidential.
Create App
To create your first App, go to Service -> Settings -> Apps tab in Afi Backup panel and click on Create app button. This prompts the dialogue containing the following parameters:
- Name - unique name of the App (ex. Test-App-<Account-name>)
- Public/Private - App type (Private Apps - only owner tenant can install, Public Apps - any tenant can install after App review)
- Logo - (optional for Private Apps) App logo
- Description - (optional for Private Apps) description of the App. For Public Apps description should contain a brief overview of the application, including its usage scenarios.
- App URL - (optional for Private Apps) sign-in link to a third-party service integrating with Afi via the App
- Website - (optional for Private Apps) website/landing page of a third-party service integrating with Afi via the App
- Provider - allows to restrict App visibility to the accounts of specific kind (ex. only to Office 365 tenants)
- Roles - permissions which the App will have when accessing the accounts where the App is installed. Please note that Roles can't be changed after App creation.
After the creation App will appear in the Available Apps list and will be available for the installation in the current account. Newly created public App will be visible only inside its owner account and will have Verifying status. To become globally visible, a public App should be reviewed and approved by Afi team which will verify that the application has proper description, provides useful functionality to the Afi users and follows API usage best practices.
Generate API keys
Once the App is created, you will be able to generate the key for API access. To do it, click on Edit button corresponding to the App, then on Generate key button inside the Keys section and, after that, the service will prompt a dialogue with a newly generated key. Please copy and save the key on your side in a secure place as we don't store API keys on our side, only key hash. Afi allows the App to have up to 2 keys which can be regenerated so you can rotate the keys or revoke compromised ones.
For API description and usage examples, please refer to the Afi Platform API documentation.
Install App
To allow the App to access an account, you need to install it. Once the App is installed, it will be shown under Installed Apps section.
Uninstall App
To revoke the App access to the account, click on the Edit button and then on Uninstall button inside the App edit window. Please note that it might take up to several hours to revoke the App access to the account.