Approov CLI Tool Reference

Overview

The Approov command line tool is used for administering the operation of your Approov service. Builds of the tool are available for Linux, MacOS and Windows. All commands require a valid management token. The general form of all commands is:

approov <command> [<management-token-path>] [option]...

A full list of valid commands can be obtained by invoking the tool with no parameters. The valid command arguments are api, appsigncert, device, devicecheck, filter, management, metrics, monitoring, metrics, pin, policy, registration, safetynet, sdk, secret, token and whoami. The options available for each of those commands is provided in the following sections. Help for any command can be obtained by invoking with:

approov <command>

The management token may be specified as a path as the second parameter or, alternatively, the token may be held in the environment variable APPROOV_MANAGEMENT_TOKEN. If specified on the command line then this overrides any environment variable token.

An Approov 1 backwardly compatible version of registration options is made available by invoking the tool with an executable name registration (or registration.exe for Windows). More details at Approov Legacy Registration Tool Mode.

API Command

approov api [<management-token-path>] [option]...
Option Description
-add <domain> Adds the given new domain to the set that Approov tokens will be served for. By default a leaf certificate public key pin will be set for the domain. A check is made that the local and remote views of the certificate at the given domain endpoint are the same, and the domain will not only be added if so. This behavior can be changed using the -pinType option. Note that additions are immediately added into production apps so that they are able to obtain Approov tokens for the given domain.
-check Checks all of the API domains to ensure that they are both accessible and that the pins specified match at least one certificate in the chain. The certificate chain is obtained via a local network access. This command can be used in a periodic check script to generate some kind of alert if the pins are incorrect and may be causing app failures in production.
-jwe Used in conjunction with the -add option to specify that the newly added API domain that have encrypted JWE Approov tokens issued for it.
-list Lists all of the API domains on which Approov tokens are served for this account. Also shows if an API domain uses JWE Approov tokens.
-pinType <type> Selects the type of leaf public key pin that will be obtained for the -add command. Possible options are as follows:
  • matching: This is the default. It indicates that a leaf pin should be obtained both via local network access and remotely using the Approov servers. They must match for the operation to succeed.
  • local: Indicates that the pin used should be the one obtained from local network access.
  • remote: Indicates that the pin used should be the one observed by the Approov servers rather than the one obtained from local network access.
  • none: Indicates that no pin should be obtained and can be used to add a new domain where no pin is added.
-port <number> If -pinType local is used then number specifies the port that should be connected to if it is not the standard of 443.
-remove <domain> Removes the given API domain from the set on which Approov tokens are served. Note that this has an immediate impact on production apps so must be used with care. An administration level management token is required to perform this operation.
-setAll <pathname> Sets all of the API domains and the pinning information for the account. The format of this file is explained in Public Key Pinning. Note that this may also be used to determine which API domains will server JWE (as opposed to JWS) Approov tokens using the jwe flag as pin for the domain. An administration level management token is required to use this option and the impact on production is immediate so care must be taken with any modifications. An initial check of the domains is performed first to give the user confidence that they are correct.

App Signing Certificates Command

approov appsigncert [<management-token-path>] [option]...

Note that the appsigncert command can also be used with a delegate management token.

Option Description
-add <file> Adds the given app signing certificate in the given file. This should have a .der extension. Once added, apps released via the Android App Bundle process that are signed using this certificate are considered to be valid, as long as there is also a matching app registration.
-list Lists all of the app signing certificates that are currently active, along with some metadata and their fingerprint hashes.
-remove <hash> Removes the app signing certificate with the given fingerprint hash. Note that this has an immediate impact on production apps so must be used with care. An administration or delegate level management token is required to perform this operation.

Device Command

approov device [<management-token-path>] [option]...
Option Description
-add <device-ID> Adds the given device-ID to the set that have an explicit override security policy for them. The device-ID is a base64 encoded identification string that can be obtained from logging on the device or from the did claim in an Approov token generated on the device. The -policy option may be used in conjunction with this option to determine the specific policy to be set for the device, otherwise the current security policy for the account is used. The -pinMode option may be used in conjunction with this option to determine the pinning mode for the device, otherwise the default pins are used. Note if a particular device-ID has previously had a policy set for it then this option allows the previous settings to be updated.
-banMode <mode> This option may be used in conjunction with the -add option to ban or unban a particular device ID. When used in combination with iOS DeviceCheck is also allows permanent physical device banning. This specifies a particular banning stance for the device with the selected ID where mode means:
  • query: Indicates that banning should be based on the current state of the bits for a physical device as held by Apple. This is the default.
  • ban: Indicates that when the device next tries to attest it should be marked as banned, and is no longer able to receive valid Approov tokens.
  • unban: Indicates that when the device next tries to attest iit should be marked as unbanned (which has higher priority than a banned state). Thus it should be able to receive valid Approov tokens again if it otherwise meets the required criteria.
-clear This is used in conjunction with the -getFetches or -getInfo new-did options to clear the currently held state of past fetches or new devices added. This ensures that the next get will not return duplicate information.
-clearDeviceState This clears any persisted device state for the account. This option requires an administration level management token.
-getDeviceState <device-ID> Gets any persisted state for the given device-ID. In particular this provides information about the DeviceCheck or SafetyNet state for a device, or any banning that has been applied to it. The device-ID is a base64 encoded identification string that can be obtained from logging on the device or from the did claim in an Approov token generated on the device.
-getFetches <timing> Gets the device IDs of up to the most recent 1000 that have requested Approov tokens for the account. If the timing parameter is timed then the timestamp of the request is shown. It is not present if untimed is used.
-getInfo <device-ID> Gets detailed information about the given device-ID if it has been previously added as a custom device using -add and it has made a token fetch since then. The time of the information capture is shown. The information provided may be used by the filter commands. If device-ID is specified as new-did then information is provided for up to the last 100 new devices IDs that were seen on the account.
-label <name> Used in conjunction with -add to set a particular user label name on a device (max 32 characters). This is helpful for identifying the relationship between device IDs and specific devices.
-list Lists all of the devices that have explicit override policies set for them. This also lists the name of the user (obtained from their management token) that last set the policy for the device to help determine the user of the device. Note, however, that any management token can be used to remove any device from the list.
-pinMode <value> This option may be used in conjunction with the -add option to specify a particular pinning mode for the device. If an option is used (other than the default pin) then this causes a custom dynamic configuration to be sent to the device the next time it connects. Pinning mode options are as follows:
  • pin: Indicates that pinning should be applied as normal to the device, this is the default.
  • unpin: Indicates that all pins for the device should be removed. This can be used for analysis or pentesting when it may be necessary to allow analysis of the app’s communication.
  • block: Indicates that a pinning failure should be forced on all user specified domains that have any pins set.
  • blockAll: Indicates that a pinning failure should be forced on all user specified domains and the Approov SDK communication with the Approov cloud. This will typically cause a MITM_DETECTED error.
-policy <policy> This option may be used in conjunction with the -add option to set the specific policy for a device. This is provided as three comma separated items as follows in the given order:
  • rules-policy: Name of the overall rules policy to be used, typically default.
  • rejection-policy: Policy to be used to determine which devices to reject so that they do not obtain a valid Approov token.
  • annotation-policy: Policy for the inclusion of some characteristics of the device in the anno claim of Approov tokens.

A full list of available policy combinations is available in the Security Policies section.

-probeURL <url> Used in conjunction with -add to a probe url for the device. This URL should include the https:// scheme and may optionally include a port number using the standard : notation. The device will obtain the certificate chain observed and provide it via the -getInfo option.
-remove <device-ID> Removes the given device-id from the list that have an explicit override policy. The device will then default to use the standard policy for the account.

DeviceCheck Command

approov devicecheck [<management-token-path>] [option]...

Note that the devicecheck command (apart from -get) requires the use of an admin level management token. A delegate management token may also be used.

Option Description
-addAuthKey <auth-file> Adds a DeviceCheck key to your account and enables the use of Apple DeviceCheck in your account. The key is downloaded from the Apple developer portal and should be of the form AuthKey_ID.p8, where the ID is the identifier for your particular key. The key must have been granted DeviceCheck privileges. Note that the -teamID option must also be specified.
-bits <value> This determines the individual bits which are available for usage by Approov. Apple allows up to two bits to be persisted for each physical device under your Apple developer account. If bit0 or bit1 is specified then only that bit will be used by Approov and your are free to use the other bit for your own purposes. If both is used then this enables the automatic banning feature which uses both bits. If not specified then none is assumed, and the device token is just used to prove the presence of a real iOS device.
-dev By default the Apple production endpoint (https://api.devicecheck.apple.com) is used. If this option is specified then the development endpoint (https://api.development.devicecheck.apple.com) is used instead.
-expiry <duration> This specifies an expiry duration for any device bans in terms of months. This means that if the last update is older than the specified period then the bits are considered to be cleared. The default period is 12 months. The parameter should be specified as a numeric value followed by m (e.g. 1m for one month).
-get Gets the current device check information.
-remove Removes the device check information from the account.
-teamID <ID> This option must be used in conjunction with -addAuthKey and specifies the team identifier for your apps. This identifies apps as being issued by your team and is required in order to make calls to Apple APIs to get and update the device check bits.

Filter Command

approov filter [<management-token-path>] [option]...
Option Description
-add <filter-name> Adds a new filter to your account with the given filter-name. The -key and -matchValue options must also be used to specify the key and value that should be matched against. Note that filter-name is restricted to 20 characters and must be composed of lower case letters, digits and - only.
-ban This may be used in conjunction with the -add option to cause any match on the filter to automatically ban the device ID that matches. This option should be used with care, as if the match is too generic then large numbers of devices in the account could be affected. If you need to clear all of the device bans in the account then the -clearDeviceState in the device command can be used, but this requires an administration level management token.
-key <value> This may be used in conjunction with the -add option and specifies the particular key that is being tested with the match. The individual key names are determined from those presented in the -getInfo results using the device command.
-list Lists all of the current filters that are active.
-matchValue <value> This may be used in conjunction with the -add option and specifies the particular value that must be matched for the specified key. Individual possible values are presented in the -getInfo results using the device command.
-new-did-only This may be used in conjunction with the -add option and specifies that the match must only occur for new device IDs that have not been previously seen.
-remove <filter-name> Removes the filter with the given filter-name.

Management Command

approov management [<management-token-path>] [option]...

Note that the management command requires the use of an admin level management token.

Option Description
-add <params> Adds a new management token for a new user. By default this will be a developer token, but an administration token may be added by using the -admin option or a delegate token may be added by using the -delegate option. The params are composed of three comma separated parameters as follows:
  • user-email: Email address of the user that the token is being issued to. This is simply used as a label to uniquely identify the user.
  • user-name: Name of the user that will be included in the token. Note that to accommodate spaces in the name single quotes can be used around the whole of params.
  • duration: The duration of the issued token, such as 30d to indicate 30 days. Available suffixes are y (years),d (days) and h (hours). Note that it is not possible to create a new token with a duration that is longer than that of the admin token being used to create it.

The result is the string representing the new management token. This should be communicated securely to the new user.

-admin Used in conjunction with the -add option to add a new administration, rather than development, token.
-delegate Used in conjunction with the -add option to add a new delegate, rather than development, token.
-file <pathname> Used in conjunction with the -add option to write the new management token to the given pathname.
-list Lists all of the management tokens which have the same or earlier expiry times than the administration level token used to access this information. This provides the user name, email, expiry time and the management token string that can be used to resend to the user or to revoke. This information should be treated carefully and not stored in any easily accessible files.
-revoke <token> Revokes the given token string. A revoked token can no longer be used for any operation. Token revocation can be performed if there is a concern that the security of a given token has been compromised, or a management token holder is no longer part of a development project.

Monitoring Command

approov monitoring [<management-token-path>] [option]...

Note that most monitoring commands (apart from getting the -getHealthCheckURL) requires the use of an admin level management token.

Option Description
-add <email> Adds a new email to the monitoring recipient list. This email will be sent a summary of monthly activity at the end of the billing period. If daily summaries are enabled then a daily summary will also be sent at midnight UTC. Note that no email confirmation is sent, so care must be taken to enter a valid email address.
-get Gets the current monitoring configuration, showing the summary period, email recipients and any emergency contact set.
-getHealthCheckURL Gets the URL to be used for any monitoring of the health of the primary Approov service.
-remove <email> Removes the given email address from the list of those that will receive summaries of account activity.
-selectDailySummary Selects the option to receive daily summaries of account activity.
-selectMonthlySummary Selects the option to receive monthly summaries of account activity.
-setEmergencyContact <info> Provides a string providing emergency contact information in case we need to contact you urgently about service operation. This may be an email but ideally should include some means for contact outside of normal office hours.

Metrics Command

Access to the Grafana based metrics dashboards can be initiated without any further options. Simply use:

approov metrics

Pin Command

approov pin [<management-token-path>] [option]...
Option Description
-add <pin> Adds the given pin to the domain specified with -api. The pin should be specified as a base64 encoded 256-bit value, representing a subject public key hash, which is deemed acceptable for a connection to the domain.
-api <domain> Specifies the API domain that various other options are acting upon. If adding or removing pins then this should be a domain that has already been added to the account.
-forceApplyPins Forces application of the current level of pinning to all clients whose last obtained pins via a getPins call was to an earlier version. This asserts the isForceApplyPins flag for future token fetches on those apps and the implementation should ensure that pin bindings are updated at the earliest convenience.
-getCertChainPins Obtains the public key pins for the certificate chain for the domain specified with -api. The leaf certificate is shown first and then the chain right up to the root certificate. The public key pin, expiry date and subject information is provided for each element in the chain. This can be used to obtain the pins for intermediate certificates.
-getCertPin <file> Extracts the public key pin for the certificate provided in the given file. This must be a base64 encoded PEM certificate. This can be used for obtaining the pin for a certificate that has not yet been put into active usage. The expiry date and subject information is also provided. Note that no -api is required.
-getLeafPin <type> Obtains the public key pin for the leaf certificate at the domain specified with -api. The type specifies the pin extraction requirement and may one of:
  • matching: Check local and remote pins and ensure they match.
  • local: Extract the pin as observed via local network access.
  • remote: Extract the pin as observed by the Approov servers,
-list Lists all of the pins associated with the API domain specified with -api.
-port <number> If -getLeafPin local or -getCertChainPins is used then number specifies the port that should be connected to if it is not the standard of 443.
-remove <pin> Removes pin from the API domain specified with -api.

Policy Command

approov policy [<management-token-path>] [option]...
Option Description
-get Gets the current security policy being applied to the account. This is provided as a comma separated string composed of the rules policy, rejection policy and annotation policy as required by the -set option. However, more detailed information is also provided including a description of the impact of the current policy settings.
-getIPTracking Gets the current IP tracking setting for the account, which may be token, full or none.
-set <policy> This sets the overall security policy for the account. It is provided as three comma separated items as follows in the given order:
  • rules-policy: Name of the overall rules policy to be used, typically default.
  • rejection-policy: Policy to be used to determine which devices to reject so that they do not obtain a valid Approov token.
  • annotation-policy: Policy for the inclusion of some characteristics of the device in the anno claim of Approov tokens.

A full list of available policy combinations is available in the Security Policies section. Modification of the overall security policy requires an administration level management token. It is actioned for production apps within 30 seconds.

-setIPTracking <setting> This sets the IP tracking policy for the account as follows:
  • token: The IP address of the requesting end user device will be put into the ip claim of the Approov token but all logging made by Approov servers will only include a one-way hash of the IP addreses. This is the default behaviour for an account.
  • full: The IP address of the requesting end user device will be put into the ip claim of the Approov token and may be logged by Approov systems.
  • none: The IP address is not present in the Approov token and is only stored as a one-way hash by the Approov server side systems.

Registration Command

approov registration [<management-token-path>] [option]...
Option Description
-add <app-path> Adds (or updates) an app registration for the app package with the given app-path. This package must have an extension of .ipa for iOS or .apk / .aabfor Android. The required signature characteristics are extracted from the app and transmitted to the Approov cloud service. New registrations are active within 30 seconds. Note that it is important that the package provided is exactly the same one as will be provided in the app store. If an Android .aab is being registered then the bundletool must be accessible, and the appropiate app signing certificates need to have been added.
-bundletool <path> Location of the bundletool jar file that is needed if adding a registration of an Android .aab file. If this is not specified then the environment variable APPROOV_BUNDLETOOL can be used to specify the location instead.
-cloneTo <path> Clones permanent app registrations to the accounts with delegate management tokens provided in the path. This must be a directory holding only *.tok delegate token files. Note that this deletes any registrations in the target accounts that were previously cloned but are no longer present in the account.
-expireAfter <duration> This may be used in conjunction with a -add option to set a temporary period for a registration. By default, a registration is permanent, and this means that it can only be removed using an administration token. Generally, registrations used for development purposes should be temporary and permanent registrations should be reserved for production apps. Note that if a registration already exists then it is updated to have the longest expiry time between its existing status and the new registration being made. The registration time for an app is always updated by a new registration. The options for the duration may be specified in y (years), d (days), h (hours), m (minutes) or s (seconds). Multiple time units may be used as long as they are specified in this order, e.g. 3d12h to register for three and a half days.
-libraryID <ID> The library ID against which an app is registered is normally extracted automatically from the app. If this is not possible, perhaps because the app uses the Approov SDK embedded inside some other SDK, then this option may be used in conjunction -add to specify the SDK library being used.
-list Lists all of the app registrations that are active for the account. They are listed in order of their registration time, so that the most recent registration is always shown at the end of the list. The full registration signature (which may be used for a -remove option) is shown, along with information about the SDK version used and the registration time. The automatic expiry time of the registration is also shown for temporary registrations.
-remove <signature> Removes the app registration with the given signature. This corresponds to the first contiguous string for the app registration obtained with the -list option. Any removal of the registration will have an impact on production apps within 30 seconds. Note that permanent app registrations can only be removed with an administration level management token or with a token issued to the same user name as used to originally register it.
-removeMatching <params> Removes multiple matching app registrations. It is designed to allow easier removal of older registrations that are no longer in active use. The params are two comma separated items as follows:
  • app-name: The app package name that must match for the removal to occur.
  • age: Specifies the minimum age for the registration time to match. This allows removal to be restricted to older registrations. The options for the duration may be specified in y (years), d (days), h (hours), m (minutes) or s (seconds).

Note that an administration level management token is required to use this option.

-versionName <override> This option may be used in conjunction with -add to overwrite the version number of the app in the registration with override. It is not advisable to use this option for permanent registrations so that the actual published app version number can be clearly seen, but for temporary development registrations this is useful for marking a particular registration with some ancillary information, such as a build number of hash from a CI system. Note that any spaces in the override value are removed.

SafetyNet Command

approov safetynet [<management-token-path>] [option]...

Note that the safetynet command (apart from -get) requires the use of an admin level management token. A delegate management token may also be used.

Option Description
-get Gets any current SafetyNet API key.
-remove Removes the SafetyNet API key from the account.
-set <value> Sets the SafetyNet API key for account. This key is transmitted down to running Approov SDKs for your apps so they can perform the attestation.

SDK Command

approov sdk [<management-token-path>] [option]...
Option Description
-accessedURLs Gets the list of different URLs that the SDK may access. This may be required in order to setup firewall rules when running the SDK inside a private network. Note that the SDK must be able to access these domains directly without any TLS interception by a firewall. This option is also valid with a delegate management token.
-bitcode This can be used in conjunction with the -getLibrary option and causes a bitcode (rather than native code) version of the iOS SDK to be obtained. We suggest you use the native version where possible for enhanced security, but the bitcode version is available when a bitcode release is mandatory for the project.
-getConfig <pathname> This obtains the latest initial configuration string for the account and saves it to the given file. This file must be integrated into the mobile app and used to initialize the Approov SDK. This option is also valid with a delegate management token.
-getLibrary <pathname> This obtains a library SDK package that can be integrated with a mobile app. It is written to the given pathname that must have an extension of either .zip (for iOS SDKs) or .aar (for Android SDKs). By default the latest SDK library that is available is obtained. Note that the library obtained may be modified with either the -bitcode or -libraryID options.
-libraryID <ID> This option may be used in conjunction with the -getLibrary option to get a specific version ID of the library. In some cases Approov support may provide you with a specific ID to obtain a library with specific characteristics or one suitable for embedding inside another SDK.

Secret Command

approov secret [<management-token-path>] [option]...

Note that the secret command requires the use of an administration level management token.

The 512-bit secret that is obtained with the -get command is the one used for checking the symmetrically signed JWS tokens. If you wish to decrypt a JWE generated by Approov then the 256-bit key is obtained by performing a SHA256 hash of the secret obtained using the command.

Option Description
-change This causes the Approov token secret to be immediately rotated with a new random value that is output by the command. Typically, this should only be done if there is a significant concern that the prior Approov secret may have been compromised. This change happens immediately so newly generated Approov tokens will use the revised secret. The -forcePrintable option may be added to force the new secret to use printable characters in its raw form.
-clearKeyID Clears any key ID that is being included in JWS tokens generated for the account.
-forcePrintable This may be used in conjunction with the -change option to force the new secret to use printable characters in its raw form. This should only be used if your JWT verification library only supports a printable secret.
-get <representation> This gets the Approov token secret in the selected representation with options as follows:
  • base64: Encoded in base64 format.
  • base64url: Encoded in the base64ul format without the optional padding characters.
  • raw: Raw binary form. However, this is only possible if the secret only contains printable characters, which will not normally be the case.

The binary secret itself is always 64 bytes (512-bits) in length. It should be integrated into backend integrations to check the validity of Approov tokens. Note that the secret should be kept with the utmost care, since it allows valid Approov tokens of arbitrary lifetime to be generated. The token secret itself should never be included in the mobile app or any software in the public domain.

-getJWK This gets the Approov token secret in the JSON Web Key (JWK) format. This may be an easier for integration with those backend systems which support this format.
-getKeyID Gets any key ID that has been set in the account and will appear in the kid field in any JWS headers.
-setKeyID <id> This sets the specific id to become the label for the Approov secret and this will appear in the kid field in the header of JWS tokens for the account. This will also be provided in any JWK obtained with -getJWK.

Token Commands

approov token [<management-token-path>] [option]...
Option Description
-check <token> Checks the validity of the provided token value. This shows if the token is valid (or expired) or not and also decodes the contents of the token. This works with either JWS or JWE Approov tokens. Note that a LoggableToken may be provided, in which case its validity may be checked.
-genExample <domain> Causes an example Approov token to be generated for the given domain. This must be a domain that has been previously added to the account so that Approov tokens can be generated for it. The generate token will have an expiry time of 1 hour to allow it to be used for testing backend integrations. By default the token will be valid, but this can be changed with the -type option. A JWE Approov token is generated if the selected API domain is configured to do this. The token will include typical example claims. A data hash pay claim may be added using the -SetDataHashInTokenOption.
-genLongLived <params> This generates a long lived Approov token that is valid for a longer duration. This is useful to enable server-to-server communication to an API protected with Approov. Long lived tokens should never be put into public clients, such as mobile apps or web pages. The params consists of two comma separated entries:
  • Issuer: This is a string that is placed in the iss claim of the Approov token to identify different sources of long lived Approov tokens.
  • Duration: Provides a duration for the Approov token such as 30d to indicate 30 days. Available suffixes are y (years) and d (days).
Note that this option requires the use of an admin level management token.
-setDataHashInToken <data> This can be used in conjunction with the -genExample option to set the hash in the pay claim of the Approov token. The data parameter should be the data (as would be passed to the similarly named SDK method) to be hashed and bound to the token. This can be used for checking the token binding checking in backend API integrations.
-type <state> Sets the type of an example Approov token. This option may be used in conjunction with -genExample in order to select a token type other than a valid one. Options for state are as follows:
  • invalid: Generates a token that is not signed with the token secret and provides an Approov token that represents a rejection.
  • failover: Generates a token that might have been produced in failover mode and does not contain various claims.
  • valid: Produces a valid token (note that this is the default)

Whoami Command

This provides information about the management token being used to access the Approov service, either the one added to the APPROOV_MANAGEMENT_TOKEN environment variable or one explicitly provided on the command line. The name of the account and the information about the user the token was issued to is provided, along with the expiry time of the token. To get this information simply use:

approov whoami