Account and User Commands
Overview
The Approov Command Line Interface (CLI) is used for administering the operation of your Approov service. Builds of the tool are available for Linux, MacOS and Windows. Follow the Approov CLI Tool Installation instructions if you do not have it installed.
The general form of all commands is:
approov <command> [option]...
A full list of valid commands can be obtained by invoking the tool with no parameters. The valid command values are account, api, appattest, appsigncert, customjwt, device, devicecheck, filter, forcefail, forcepass, init, installattrs, keyset, metrics, monitoring, password, pin, playintegrity, policy, registration, role, sdk, secret, secrules, secstrings, support, token, users, web and whoami. The options available for each of those commands are provided in the following sections. Help for any command can be obtained by invoking with:
approov <command>
Note that the metrics, support and whoami commands do not accept any arguments and so they do not print help text.
In order to execute operations you must have initialized access to Approov. This is typically done by executing an approov init command with an onboarding code received by email.
In certain specific circumstances access may be provided via a management token held in the environment variable APPROOV_MANAGEMENT_TOKEN or as an optional command line parameter after the command argument:
approov <command> [<management-token-path>] [option]...
Using either of these options overrides the default permissions lookup and specifying the command line argument overrides the environment variable setting.
Users Command
approov users [option]...
Note that the users command requires the use of an admin role.
| Option | Description |
-add <email> | Provides access to the Approov account for the user with the given email address. By default a dev role will be provided, but the -admin, -delegate, -pentest or -automation options may be used to change the role. If the automation role is selected then the new management token is saved locally. Otherwise, the user will receive an onboarding code by email which they can use to initialize their approov CLI. The user name is extracted from the email address, but it can be overridden with the -userName option. Normally the user will be required to set a password for access, however, the automation role doesn't use a password and the -noPassword option may be used to override this behavior for other roles. |
-admin | Used in conjunction with the -add option to issue admin role access. |
-automation | Used in conjunction with the -add option to issue automation role access. |
-delegate | Used in conjunction with the -add option to issue delegate role access. |
-expireAfter <duration> | Used in conjunction with the -add option to specify a lifetime for user access, such as 30d to indicate 30 days. Available suffixes are y (years),d (days) and h (hours). Note that it is not possible to provide access for longer than that afforded to the admin role used to create it. |
-file <pathname> | Used in conjunction with the -getManagementToken option to write the management token to the given pathname. |
-getManagementToken <role-id> | Gets the raw management token with the given role-id. It is written to a file with a name of the role-id. Typically this should only be used if you wish to obtain a previously created automation role management token. You can change the filename using the optional -file option. |
-list | Lists all of the user roles in the account. This provides a role ID, type, email, user name and expiry time for each role. An indication is also provided if the user role is password protected. |
-noPassword | This is used in conjunction with the -add command to indicate that there should be no requirement to set a password for the newly created user role. |
-pentest | Used in conjunction with the -add option to issue pentest role access. |
-revoke <role-id> | Revokes the user role with the given role-id so that account access is no longer possible. This is typically done if there is a concern about a security compromise or if a user leaves a development project. Note that it is not possible to revoke the user roles initially provided when you signed up for your Approov account. If you are concerned that these have been compromised then please contact Approov support. |
-sendOnboardingTo <email> | Sends an onboarding email to the given email address allowing access to any roles associated with the user with that address. At least one role must be associated with that email. This provides a means to restore Approov access to users that have lost access for whatever reason, or wish to move their access to a new or additional machine when their original onboarding email has expired. |
-userName <name> | Can be used in conjunction with the -add option to set the user name for the new user role. Note that to accommodate spaces in the name single quotes can be used around the whole of name parameter. |
Init Command
approov init [options]
| Command Form | Description |
<account-name> <onboarding-code> [domain] | Initializes access to Approov with the given account-name and with a time limited onboarding-code. You will have received this information in an email from Approov. You may be asked to use a specialized domain, which will also be specified in the email. This provides a recovery PIN number, which you should keep securely, in case you need to recover your access, or migrate it to another machine. If this is the first initialization, you will typically be asked to set a password. |
<account-name> <email> [domain] | Requests a new onboarding code by email if you wish to recover access to your Approov account. The account-name and email must be identical to the ones originally provided. You may be asked to use a specialized domain, that will have been specified in the original onboarding email. When you issue this command you will be asked for the recovery PIN number that was provided when you first performed the initialization. |
<management-token-path> | This allows an existing management token, held in a file at management-token-path, to be initialized into your machine configuration. It can then be selected using the standard role mechanism. This is primarily for Approov customers that were issued management tokens prior to the introduction of the role feature. Note that this will automatically send a password reset code email that you can use to setup a password for the management token access. |
remove-all | Removes all of the access roles installed on the machine. Be sure that you have a way of restoring any that you need (via an unexpired onboarding email or via the email recovery flow with a PIN) if you use this option. |
Password Command
approov password [option]...
| Option | Description |
-clearWithCode <code> | Clears use of passwords for the user role, given a reset code previously received via email (initiated with the -sendCode option). |
-sendCode | Sends a password reset code to the email address embedded in the user role being used. This code can then be used on a subsequent command for a password to be reset (with -setWithCode) or cleared (with -clearWithCode). |
-setWithCode <code> | Sets a new password for the user role, given a reset code previously received via email (initiated with the -sendCode option). You will be asked to enter a password (of at least six characters) and then again to ensure it has been entered correctly. |
Role Command
approov role <role> [<account>]
This command allows a specific role to be selected from those that have been installed on the machine using approov init. The first parameter is the required role type, such as dev or admin. If you have installed roles for multiple Approov accounts then you must additionally specify the account name as a second parameter.
Using this command extends any active session for the role to a full hour (if it is protected by a password). You can use approov role . to extend the session for the current role without needing to reselect it.
The primary output of this command on stdout is a string to be evaluated to set a new active role in the APPROOV_ROLE environment variable. Errors are output on stderr. On Windows the environment variable must be set directly. Use approov role to see the list of available commands.
Support Command
This provides information about reaching our support team. If you have a paid subscription then this provides additional information about our emergency contact information that you can use if you have an urgent problem causing a production outage. To get the information simply use:
approov support
Account Command
approov account [option]...
| Option | Description |
-setDisplayName <display-name> | Sets the display name for the account. The display name, if set, is shown alongside the account ID in logging, emails and the CLI and allows you to distinguish more easily between accounts if you have more than one Approov account. The display name may be between 1 and 100 characters in length, must start and end with an alphanumeric character and contain only letters, numbers, dots, underscores, hyphens, the '@' symbol and spaces. Use approov account -setDisplayName "" to unset. |
-getInfo | Shows overall account configuration information about features and limits that are not user changeable. See the tables below for explanations of the individual features and limits defined in the account. Please contact Approov support if you need any features to be enabled or disabled or would like to request for any limits to be changed. |
| Features | |
|---|---|
| AppAttest | Shows whether the account is enabled to use the integration with Apple's AppAttest. |
| JWE Tokens | Shows whether the account permits the use of JWE tokens. |
| Key Sets | Shows whether the account allows users to manage keys using key sets. |
| Measurements | Shows whether Offline Security Mode has been enabled for the account. |
| Play Integrity | Shows whether the account is enabled to use the integration with Google's Play Integrity. |
| Proxied Attestations | Shows whether the account has been configured to work when attestation requests are routed through a proxy. |
| Secure Strings | Shows whether the secure strings feature is enabled in the account. |
| Token Lifetime | The lifetime in seconds given to Approov tokens obtained from the Approov service. |
| Web Protection | Shows whether the Web Enabled API feature is enabled in the account. |
| Limits | |
| API Count | Maximum number of APIs that may be used in the account. |
| App Signing Certificate Count | Maximum number of app signing certificates that may be added to the account. |
| Attestations per Minute | The maximum permitted number of attestations per minute and per attester for the account, which can be unlimited. If a limit is set, only the attestations within that limit return Approov tokens that are based on proper attestations performed by the Approov service. Any attestation requests beyond the limit return a valid Approov token by default. |
| Attestations per Month | The maximum permitted number of attestations per month for the account, which can be unlimited. If a limit is set, only the attestations within that limit return Approov tokens that are based on proper attestations performed by the Approov service. Any attestation requests beyond the limit return a valid Approov token by default. |
| Custom Devices Count | Limit for the number of custom devices for the account. |
| Devices per Month | The maximum permitted number of unique devices per month for the account, which can be unlimited. If a limit is set, only unique devices within that limit receive Approov tokens that are based on proper attestation results performed by the Approov service. Any devices beyond the limit get valid Approov tokens by default. |
| Force Fail App Count | Limit for the number of app versions that can be added to the account to be forced to fail. |
| Force Fail Device Count | Limit for the number of devices that can be added to the account to be forced to fail. |
| Force Pass Device Count | Limit for the number of devices that can be added to the account to be forced to pass. |
| Key Set Size | If key sets are permitted, then this is the limit for the number of keys that can be added to a key set in the account. |
| Predefined Secret Count | Limit for the number of predefined secure strings in the account. |
| Registration Count | Limit of the number of app registrations for the account. App registrations using app signing certificates do not count towards this limit. |
| Throttle Attestations at Load | Shows whether attester load is used to limit the number of attestations for this account. |
| User Role Count | Limit for the number of user roles for the account. |
Whoami Command
This provides information about the role being used to access the Approov service, typically the one previously selected with approov role. The name of the account and the information about the user and expiry of the access is provided. If access is provided via an APPROOV_MANAGEMENT_TOKEN environment variable or a management token explicitly provided on the command line then this information will be provided. To get this information simply use:
approov whoami