Approov Installation

Setup

Requirements

In order to integrate Approov you will need the following:

  • Approov account. You can sign up for a free trial. You will receive an email with the subject Approov Onboarding with activation information.
  • Approov tool that can be downloaded directly from here or via the Brew package manager.
  • Server exposing the API that you want to protect.
  • Android and/or iOS app that communicates with that API.
  • Development environment to compile the app. More detailed software requirements are in the Android SDK Integration and iOS SDK Integration sections.

Initializing the Approov CLI

All management of the Approov account is done using a Command Line Interface (CLI) tool available for Linux, MacOS and Windows and downloaded from here. Alternatively, for Linux and MacOS you can use Brew to install the Approov CLI. We suggest you use Brew if you already have it installed for other tools, otherwise use a direct download and installation.

Examples, showing how to use this tool, are provided throughout the documentation and a detailed reference for all the commands can be found in the Approov CLI Tool Reference.

The first step in using Approov is to install this tool on your system and then initialize it using the information provided in the Approov Onboarding email. If you are the account owner, initialization will grant account access with dev (development) and admin (administration) level roles available. Most operations can be carried out using the dev role, but the admin role is necessary for certain operations needing elevated privileges. If you received your Approov Onboarding email as a result of being added to an existing Approov account then you will be provided with a specific access role.

Follow the instructions to install the Approov CLI directly on Linux, MacOS or Windows. Once you have done this can proceed with the remainder of these instructions. Use Brew Installation if desired instead for Linux or MacOS.

Initialize access to your Approov account using the information from the Approov Onboarding email. Copy and paste the instruction from the email, such as:

$ approov init myaccount 542f15e4-6224-43c2-8e4b-015c5a5251cd
IMPORTANT: your recovery PIN is 287572 - make a note of this in case you ever need to recover your access
please provide a password (6 characters or more) to protect access
enter password:
confirm password:
approov access has been initialized
available role selection commands for account myaccount:
  eval `approov role admin`
  eval `approov role dev`

If approov cannot be found then there has been an issue with the OS specific installation.

This operation grants access to your Approov account from your machine. The parameter myaccount is the identifier of your allocated Approov account. The next parameter is a time limited onboarding code for your account.

You will normally be invited to choose a password for your access to Approov. If your onboarding included a dev role then this will be automatically selected for subsequent uses of the Approov CLI. You will be invited to type in the password again on first usage, and after every one hour session expires.

Note that you are also provided with a PIN number. You should make a note of this somewhere private and secure, it will be needed if you ever need to recover access to your account via email. The PIN provides an additional level of protection for your Approov account in case access to your email account is compromised.

You are now ready to start using Approov!

If you have been issued with older style Approov management tokens then you can import them to use with the latest CLI with access roles.

If a new version of the tool becomes available then an upgrade availability message will be shown when you invoke the tool. This will provide a link to the new version.

If you are setting up Approov on a new machine but you original onboarding email has expired, but you still have access to Approov on a different machine then you can resend onboading email using it to get a fresh onboarding email.

Installation on Linux

The download package includes a Linux subdirectory containing the approov executable. This should be placed in a directory that is on the $PATH. All examples in the documentation assume the approov tool is on the path and can be invoked directly.

Linux systems normally expect a bin directory at ~/bin or ~/.local/bin, and automatically include them in your $PATH. So you could, for instance, write the approov executable to ~/bin or ~/.local/bin, which should already be on your $PATH. If you prefer you can add it to /usr/local/bin instead, but you will need sudo permissions to copy it there.

Alternatively, you can create a new approov directory in your home directory (or other location of your choice) and then add this directory to your $PATH defined in the ~/.bashrc (or other, depending upon the shell used). For example the following can be added if the approov executable has been written to ~/approov-tool:

PATH=~/approov-tool:$PATH

When you install the Approov CLI tool in a custom location, such as ~/approov-tool, and after you add this location to the $PATH in your ~/.bashrc, you need to reload your shell source ~/.bashrc, otherwise invoking approov will fail.

Installation on MacOS

The download package includes a MacOSsubdirectory containing the approov executable. This should be placed in a directory that is on the $PATH. All examples in the documentation assume the approov tool is on the path and can be invoked directly. We suggest you write the approov.exe executable to /usr/local/bin which should already be on your $PATH. You will need sudo permissions to copy it there.

Installation on Windows

The download package includes a Windows subdirectory containing the approov executable. This should be placed in a directory that is on the $PATH. All examples in the documentation assume the approov tool is on the path and can be invoked directly.

Installation using Brew

Follow the Brew installation instructions if you do not already have it installed. To install the Approov CLI use:

brew update
brew install approov/cli/approov

If a new version of the Approov CLI becomes available then this will be shown in a message when you use the CLI. You can update with:

brew upgrade approov