Home > Approov CLI Reference

Approov CLI Reference

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 api, appattest, appsigncert, customjwt, device, devicecheck, filter, forcefail, forcepass, init, keyset, metrics, monitoring, password, pin, playintegrity, policy, registration, role, safetynet, sdk, secret, secstrings, support, token, users, web 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>

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.

API Command

approov api [option]...

Option	Description
`-add <domain>`	Adds the given new `domain` to the set that Approov tokens will be served for. By default the tokens will be signed with the `HS256` algorithm using the account secret key. This may be overridden using the `-jwe`, `-keySetKID` or `-noApproovToken` options. Also by default, a leaf certificate public key pin will be set for the domain. A check is made to ensure that the local and remote views of the certificate at the given domain endpoint are the same; the command fails with an error if the checks don't pass. This behavior can be changed using the `-pinType` option. Note that additions are immediately added to all registered apps so that they are able to obtain Approov tokens for the new domain.
`-allowWeb`	Used in conjunction with the `-add` option to specify that the API domain may have web protection requests fetched for it (see `approov web`). Should not be used with `-noApproovToken`.
`-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 and is shown in the output, along with the pins being matched against.
`-getAll <pathname>`	Gets all of the API domain attribute information and the pinning information and writes it to a JSON file with the given `pathname`. The format of this file is explained in API configuration.
`-getWildcardMode`	Gets the wildcard Approov token mode. If the status is `on` then failing Approov tokens are provided on all domains, instead of the Approov token fetch returning an `UNKNOWN_URL / unknownUL` error. This can be used for initial discovery of which API domains are being accessed by an app.
`-jwe`	Used in conjunction with the `-add` option to specify that the specified API domain should use encrypted Approov tokens (JWEs). This option should not be used with `-keySetKID` or `-noApproovToken`. This will change the token generation to use the account symmetric secret with the `A256GCMKW` encryption algorithm to generate JWEs for the API instead of JWSs.
`-keySetKID <type>`	Used in conjunction with the `-add` option to specify that the API domain should have tokens signed or encrypted using the specified key from the `keyset`. Should not be used with `-jwe` or `-noApproovToken`.
`-list`	Lists all of the API domains set for this account, along with the `type`, the applied signing or encryption algorithm (`alg`) and any key ID (`kid`). Possible types are as follows: `account`: Default, meaning that the account secret and basic signing or encryption algorithms are being used. `keyset`: Indicates that the signing or encryption key has been selected from the `keyset`. `none`: Indicates that no Approov tokens are being sent for the domain. `restricted`: Indicates that Approov has automatically assigned the algorithm and keys for the domain.
`-noApproovToken`	Can be used in conjunction with the `-add` option to specify that the no Approov token needs to be sent on requests to the domain. Fetches to obtain a token for the domain will result in a `UNPROTECTED_URL`/`unprotectedURL` status response. This is to allow Approov to be used to provide pinning facilities or managed trust roots on additional domains that do not require the use of Approov tokens. Should not be used with `-keySetKID`, `-allowWeb` or `-jwe`.
`-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>`	Customizes the target port for the TLS connection (defaults to 443). Custom ports must be in the range 1024 to 65535.
`-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 `admin` role is required to perform this operation.
`-setAll <pathname>`	Sets all of the API domain attribute information and the pinning information from the JSON file with the given `pathname`. The format of this file is explained in API configuration. An `admin` role 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.
`-setWildcardMode <state>`	Enables on disables wildcard Approov tokens mode, depending if `state` is `on` or `off`. If wildcard tokens are enabled then failing Approov tokens are provided on all domains, instead of the Approov token fetch returning an `UNKNOWN_URL / unknownUL` error. This can be used for initial discovery of which API domains are being accessed by an app.

AppAttest Command

approov appattest [option]...

Note that appattest commands (apart from -get) requires the use of an admin or delegate role.

Option	Description
`-addAuthKey <auth-file>`	Adds a DeviceCheck key to your account and enables the use of Apple AppAttest fraud lookup 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.
`-addTeamID <ID>`	This option enables the use of AppAttest for your iOS apps. The `ID` is the Apple team identifier for your Apps.
`-get`	Gets and shows the current state of the AppAttest configuration.
`-remove`	Removes use of AppAttest in your account.
`-removeAuthKey`	Disables use of fraud lookups for AppAttest.
`-setAssertionPeriod <value>`	Sets the assertion period for AppAttest to the number of hours specified in `value`. This means that if an app instance is running for more than the specified number of hours, then a subsequent Approov fetch will require a new AppAttest assertion to be performed. If `always` is specified then assertions are performed on all Approov fetches, and this is the default. Note that an assertion is always performed on a new launch of the app.
`-setMaxRisk <value>`	Sets the maximum acceptable risk for a fraud lookup to the `value` specified. This is only relevant if `-addAuthKey` has been used to allow fraud lookups. The risk metric is a heuristic supplied by Apple that determines the level of attested keys for the app associated with a particular device, and a high value may indicate fraud.
`-setRateLimit <value>`	Sets the maximum number of attestations to be performed per hour for the account. This may be used to limit the number of requests to Apple when initially onboarding a large user base. If the default value of `unlimited` is used then all new app installs will perform an AppAttest.

App Signing Certificates Command

approov appsigncert [option]...

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

Option	Description
`-add <file>`	Adds the given app signing certificate in the given `file`. This may have a file extension of `.der`, `.cer`, `.pem`, `.keystore` or `.jks`. This may be a signing certificate downloaded from either the Apple or Google developer portal. In the case of Android it is also possible to use the keystore stored locally on a development machine, to use a particular key for local development signing. Once added, apps released that are signed using this certificate are considered to be valid. The options `-autoReg` or `-dev` may also be used alongside this option. The `-alias` and `-storePassword` options may also be used while reading a Java keystore file. The `-label` option may be used to specify an entry name. By default a maximum of 10 such app signing certificates may be added in an account. Note that it is not possible to add a certificate if it is already present so if you wish to change its properties then you must `-remove` it first, using the derived fingerprint which is shown in the error resulting from an overwriting attempt.
`-alias <key-name>`	This can be used when loading a `.keystore` or `.jks` file that may contain multiple different keys to specify the specific `key-name` to be used.
`-autoReg`	This may be used in conjunction with `-add` to indicate that any app signed with the certificate should be auto-registered. This means that there is no need to register the specific app using the `approov registration -add` command, avoiding the need to do this for each app build or release.
`-dev`	This may be used in conjunction with `-add` to indicate that any app signed with the certificate is associated with development. This means that the app will always pass attestation, even if being debugged, to make it easier to work with Approov during development. Furthermore the device properties will not be included in the live attestation or monthly billing metrics, so that these continue to only show real production usage.
`-label <name>`	Used in conjunction with `-add` to mark a particular entry, making it easier to identify.
`-list`	Lists all of the app signing certificates that are currently active, along with some metadata and their fingerprint hashes.
`-remove <fingerprint>`	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 `admin` or `delegate` role is required to perform this operation.
`-storePassword <password>`	This is required in conjunction with the `-add` option if reading from a password protected `.keystore` or `.jks` file.

Custom JWT Command

approov customjwt [option]...

Option	Description
`-clearKeySetKID`	Removes any keyset KID associated with the custom JWT, so that signing returns to using the `HS256` algorithm with the account secret. An `admin` role is required to perform this operation.
`-get`	Gets the current state of the custom JWT feature.
`-keySetKID <kid>`	Selects a particular keyset `kid` to be used for signing custom JWTs. This causes the `kid` claim to be added to the token header and the appropriate signing algorithm used. An `admin` role is required to perform this operation.
`-setDisabled`	Disables the custom JWT feature. Subsequent attempts to fetch a custom JWT from the app will result in a `REJECTED / rejected` error. An `admin` role is required to perform this operation.
`-setEnabled`	Enables the use of the custom JWT feature. By default the tokens will be signed using the `HS256` algorithm using the account secret. An `admin` role is required to perform this operation.

Device Command

approov device [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. If `latest` is specified then the last device ID that has requested an Approov token for the account is selected, as long as it was in the last 2 minutes and there is only one such 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 is deprecated and it is suggested that the `approov forcefail -addDevice` option is used instead. 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`, `-getInfo new-install` or `-getInfo filtered` options to clear the currently held state of past fetches or new devices. 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 `admin` role.
`-configOptions <options>`	Sets the list of configuration options that should be applied to the SDK for the particular device. A comma separated list of string `options` should be provided. This is to enable individual features that must be setup on SDK initialization, before any Approov fetching has been performed.
`-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 fetch since then (or as a new device ID previously). 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-install` then information is provided for up to 100 of the most recent newly installed apps that were seen on the account (if there have been fewer than 100 new devices since the list was last cleared, then this command will return information about all new deivces it has recorded). If `device-ID` is specified as `filtered` then information is provided for up to 100 of the most recent devices that were seen on the account with one or more matching filters with the `captureDeviceInfo` attribute set.
`-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. To help identify device users, this command includes the name of the user that last set the policy, however, any user can 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 pen testing 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: `security-rules`: Name of the overall security rules 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.
`-removeMatching <pattern>`	Removes devies from the list that have an explicit override policy that match `pattern`. The `pattern` is matched against either the user name associated with the original addition of the device or any label that has been set. The removed devices will then default to use the standard policy for the account.

DeviceCheck Command

approov devicecheck [option]...

Note that devicecheck commands (apart from -get) requires the use of an admin role. A delegate role 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 DeviceCheck information. If a key has been added to your account (`-addAuthKey`) then this checks it against the Apple endpoint and shows a warning if there is an authorization error.
`-remove`	Removes the DeviceCheck 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 DeviceCheck bits.

Filter Command

approov filter [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. Alternatively, `-conjunction` may be used to specify a filter that matches when a set of a other filters all match. 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 `admin` role.
`-captureDeviceInfo`	This may be used in conjunction with the `-add` option to cause any match on the filter to output full device information for subsequent analysis. This device information can be viewed using the `-getInfo filtered` option in the `device` command subset.
`-conjunction <filters>`	This may be used in conjunction with the `-add` option and specifies that a conjunction filter is being defined. This is a special filter that matches when all of a set of input filters match. The input `filters` parameter is specified as a list of other filter names separated by a '+' character. Note that the filters list should not include another conjunction filter. If this option is used then `-key`, `-matchValue` and `-regex` cannot be specified.
`-execFilteredSecPolicy`	This may be used in conjunction with the `-add` option and indicates that the custom filtered security policy should be executed if there is a match, and such a policy has been added as a special device (`++FilteredSecPolicy++w==`). This allows the execution of such a policy to be restricted to only certain filter matches.
`-getSamplingPercentage`	Gets the currently set sampling percentage for a custom filtered security policy, set as the special device (`++FilteredSecPolicy++w==`). This means that this percentage of the devices will be subject to this security policy rather than the account level one. The sampling is deterministic within a given day, so a given device is always sampled or not for all fetches made.
`-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. This cannot be specified with `-conjunction`.
`-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. By default a verbatim match is required, but the `-regex` option may be used to specify a regular expression. This cannot be specified with `-conjunction`.
`-newInstallOnly`	This may be used in conjunction with the `-add` option and specifies that the match must only occur for new app installs that have not been previously seen.
`-regex`	This may be used in conjunction with the `-matchValue` option to indicate that the supplied value is actually a regular expression rather than a verbatim match value. This cannot be specified with `-conjunction`.
`-reject`	This may be used in conjunction with the `-add` option to cause any match on the filter to automatically reject the device that matches, and will not receive valid Approov tokens This option should be used with care, particularly if adding a regex filter; all devices matching the filter will be rejected.
`-remove <filter-name>`	Removes the filter with the given `filter-name`.
`-risky`	This may be used in conjunction with the `-add` option to cause any match on the filter to mark the device with the `risky-device` flag. This shortens the issued Approov token lifetime to 2 minutes. This flag also appears in the annotation if the `risk` annotation is being used. Thus this can be used to specially mark devices which are suspect in some way and other measures can be taken by backend systems that observe the `risky-device` annotation flag.
`-setSamplingPercentage <percentage>`	Sets the sampling percentage for a custom filtered security policy, set as the special device (`++FilteredSecPolicy++w==`), to the given `percentage`. Note that this can be set as decimal value, allowing selections below 1%. The maximum that may be specified is 5%. This causes the given percentage of devices to be subject to this security policy rather than the account level one. A value of 0 completely disables the sampling. The sampling is deterministic within a given day, so a given device is always sampled or not for all fetches made.

ForceFail Command

approov forcefail [option]...

Option	Description
`-addApp <name>`	Adds the app with the given package/bundle `name` with the version provided using the `-appVersion` option. Once added, the specified app and version will always fail attestation. This is typically used to block older app versions when a signing certificate with auto-registration has been added. Auto-registration normally causes any app signed with that certificate to pass. An `admin` role is required.
`-addDevice <device-ID>`	This adds the given `device-ID` to the set that are forced to fail. This set has a default maximum size of 100 devices. If this limit is exceeded then the earliest added device ID is automatically deleted from the set.
`-appVersion <version>`	This must be used in conjunction with the `-addApp` or `-removeApp` option to specify a particular app version.
`-listApps`	Lists all of the apps in the force fail set. These are listed with their package/bundle name and the set of versions for that app which will fail.
`-listDevices`	Lists all of the device IDs that are in the force fail set. The list is sorted by addition time starting with the earliest and ending with the most recent addition.
`-removeApp <name>`	Removes the app with the given package/bundle `name` with the version provided using the `-appVersion` option. Once removed, the app and version will no longer be forced to fail. An `admin` role is required.
`-removeDevice <device-ID>`	Removes the given `device-ID` from the set which will always be forced to fail.

ForcePass Command

approov forcepass [option]...

Option	Description
`-addDevice <device-ID>`	This adds the given `device-ID` to the set that are forced to pass. This set has a default maximum size of 100 devices. If this limit is exceeded then the earliest added device ID is automatically deleted from the set.
`-changeDevKey`	Changes any existing development key on the account to a new random value. This means that any existing apps using the previous development key will no longer be forced to pass. This should be used if there is any concern that the development key has leaked outside of the organization. An `admin` role is required.
`-getDevKey`	Gets the development key for the account, creating one if necessary. This is a random string that can be provided inside the app after SDK initialization to force the app to be passed. It should never be released in a production version of the app. It is provided specifically for the case where an online test environment resigns apps, so they would not otherwise pass the attestation.
`-listDevices`	Lists all of the device IDs that are forced to pass. These are lists in ascending order of the last time that they were added, so the most recent addition is show at the end of the list.
`-removeDevice <device-ID>`	Removes the given `device-ID` from the set which will always be forced to pass.

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.

Keyset Command

approov keyset [option]...

Option	Description
`-add <algorithm>`	Adds a new key to the keyset suitable for use with the specified `algorithm`. Possible options are `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, `ES384` and `ES512` for JWS signing. The algorithm `A256GCMKW` may be used for JWE encryption. A new random key is generated by the Approov server. For asymmetric key types it is never possible to obtain the private key, only the public key for verification. By default the key ID is generated automatically in a numeric sequence but this may be overriden with the `-kid` option to specify a particular named ID. For some key types the `-keyLength` option may be used to override the default key length.
`-getJWKS <pathname>`	Gets a JSON Web Key Set (JWKS) format file, providing all of the public keys in the keyset. Note that if the returned set contains symmetric keys then it must be carefully secured as the associated entries can be used to sign new tokens as well as verify them. An `admin` role is required.
`-getJWKSURI`	Gets the current status of whether the JWKS URI is enabled or not. If it is then a URL on which a JSON Web Key Set (JWKS) can be obtained is provided. This only ever provides public keys.
`-getPEM <pathname>`	Gets a PEM encoded form of the public key for the key specified by the `-kid` option. It is in PKIX ASN.1 DER format. The encoded public key is a SubjectPublicKeyInfo structure, as defined in RFC5280, section 4.1. It is only possible to obtain a PEM for RSA and ECDSA key types. The public key may be used to verify the authenticity of Approov tokens generated using the specified key.
`-import <pathname>`	Imports a private key into the keyset from the given `pathname`. This file must be in JSON Web Key (JWK) format. Note that the `alg` and `use` claims must be present and must be one of those supported by Approov. The key is imported with the name specified in the `kid` claim (which must not already be present). An `admin` role is required.
`-keyLength <bits>`	May be used in conjunction with a `-add` option to override the default key length for certain key types. For RSA types (`RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`) a default key length of 2048 bits is used, but may be overridden to 1024 or 4096 bits. For symmetric key types (`HS256`, `HS384`, `HS512`, `A256GCMKW`) the default is 256 bits, but may be overridden to 128 bits or 512 bits.
`-kid <name>`	Specifies a key identifier to be used with a `-add`, `-getPEM` or `-remove` option.
`-list`	Lists all of the keys in the keyset, their algorithm and also any API domains by which they are used.
`-remove`	Removes the key from the keyset that must be specified with the `-kid` option. The removal is only possible if the key is not currently being used by an API domain. This option requires an `admin` role.
`-setJWKSURI <policy>`	Sets the JWKS enablement policy to either being `on` or `off`. If the policy is enabled then a URL on which a JSON Web Key Set (JWKS) can be obtained is provided. This only ever provides public keys. This requires an `admin` role.

Monitoring Command

approov monitoring [option]...

Note that most monitoring commands (apart from -getHealthCheckURL) requires the use of an admin role.

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.
`-addAlert <email>`	Sets the given `email` as an alert one for API monitoring failures. Only alerts will be sent to this email address, so it can be one associated with an internal DevOps reporting system. Note that no email confirmation is sent, so care must be taken to enter a valid email address.
`-addAPI <domain>`	Adds monitoring for the given API `domain` (it must have previously been added as an API). This API will then be monitored by Approov on a frequent basis to ensure it is accessible and that the configured pin is correct. An email will be sent to the monitoring recipients and any alert email if there is a problem. The port used for probing the domain can be changed using the `-port` option.
`-get`	Gets the current monitoring configuration, showing the summary period, email recipients, any alert email and any emergency contact set.
`-getHealthCheckURL`	Gets the URL to be used for any monitoring of the health of the primary Approov service.
`-port <number>`	Used with `-addAPI` to customize the target port for the TLS connection (defaults to 443). Custom ports must be in the range 1024 to 65535.
`-refreshMetricsLink`	Refreshes the metric link that may have been sent in onboarding emails or if the `approov metrics` has been used. This command should be used if there is a concern that the previous link may have been compromised. A new link is issued that will be used in future onboarding emails and uses of `approov metrics`. It is also provided as a result of this command.
`-remove <email>`	Removes the given `email` address from the list of those to receive account activity summaries.
`-removeAlert`	Removes any alert email.
`-removeAPI <domain>`	Removes monitoring for the given `domain`.
`-resumeAPINotifications`	Resumes API monitoring notifications after an email has been received. If you do not use this option then by default no more email notfications will be received for 24 hours.
`-selectDailySummary`	Selects the option to receive daily summaries of account activity.
`-selectMonthlySummary`	Selects the option to receive monthly summaries of account activity.
`-sendTestEmail`	Sends a test email to all monitoring and alert email recipients to establish if they are able to receive it okay.
`-setEmergencyContact <info>`	Provides a string describing the emergency contact details we should use to contact you urgently about service operation. This may be an email address but ideally you should also include details for use 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

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.

Pin Command

approov pin [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.
`-addLeafPin <type>`	Adds the public key pin for the leaf certificate for the domain specified with `-api`. The `type` specifies the pin extraction requirement and may be 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,
`-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 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,
`-getManagedTrustRoots`	Gets the status showing if managed trust roots are on or off.
`-list`	Lists all of the pins associated with the API domain specified with `-api`.
`-port <number>`	If `-getLeafPin` or `-getCertChainPins` is used then this customizes the target port for the TLS connection (defaults to 443). Custom ports must be in the range 1024 to 65535.
`-remove <pin>`	Removes the specified `pin` from the API domain selected with the `-api` option.
`-getPinningTestURL`	Gets the test URL that has been specified for continuous pinning testing to help ensure it has not been compromised.
`-setManagedTrustRoots`	Sets the managed trust roots to be either `on` or `off`. If managed trust roots are on then the app is provided with the trust root pins in its configuration under the `*` domain. When trust roots are on, leaf pins are not added for new API domains that are added, on the basis that they will use trust roots instead. This requires an `admin` role.
`-removePinningTestURL`	Removes the test URL that has been specified for continuous pinning testing to help ensure it has not been compromised. This requires an `admin` role.

Play Integrity Command

approov playintegrity [option]...

Note that playintegrity commands (apart from -get) requires the use of an admin or delegate role.

Option	Description
`-addCredentials <file>`	Enables Play Integrity checking by adding the Google access credentials `file`. This should be a Google service account JSON file which provides access to the Google Play Integrity API. Once the credentials have been set, it is not possible to retrieve them from Approov again. The `-get` option will only provide the key ID.
`-clearProjectNumber`	Clears any Google project number previously set using `-addProjectNumber`. If no project number is specified then only apps released in the Google Play store can receive Play Integrity tokens.
`-clearRequireAppIntegrity`	Clears any required app integrity verdicts previously set with `-setRequireAppIntegrity`. If this option is used then the app is never rejected on the basis of the app integrity.
`-clearRequireAppLicensing`	Clears any required app licensing verdicts that have been previously set with `-setRequireAppLicensing`. If this option is used then the app is never rejected on the basis of app licensing.
`-clearRequireDeviceIntegrity`	Clears any required device integrity verdicts that have been previously set with `-setRequireDeviceIntegrity`. If this option is used then the app is never rejected on the basis of the device integrity.
`-get`	Shows the current setting of Play Integrity, including any Key ID used for access and the current settings of required integrity verdicts.
`-remove`	Disables Play Integrity so that integrity tokens are not requested and no rejections will be made on the basis of any prior integrity results.
`-setCloudProjectNumber <value>`	Sets the Google Cloud Project number in the `value` order to use Play Integrity on apps not yet distributed through the Google Play store or for apps that will be distributed outside of the Google Play.
`-setRateLimit <value>`	Sets the rate limit `value` in terms of the maximum new Play Integrity attestations that will be requested per hour. By default the value will be `unlimited`, and this value may be set again any time. This allows you to conform to the usage tier associated with your app. These are expressed in terms of daily quotas, so you should divide by 24 to obtain an hourly rate limit. If the quota is exceeded then no request for a Play Integrity is made but the app is still able to run, with a request delayed for the Play Integrity token until the next time the app is launched.
`-setRecheckPeriod <value>`	By default, a Play Integrity check is performed the first time an app is launched after being installed and this is not repeated. This corresponds to the default value of `never`, which may be reinstated at any point. Another `value` in hours may be set which causes the Play Integrity attestation to be repeated the next time the app is launched and the previous attestation was more than the given number of hours ago. Note that this additional Play Integrity attestation will impose latency and will have an impact on the usage of your app's Play Integrity use quota.
`-setRequireAppCert <setting>`	Sets whether the `certificateSha256Digest` provided from a Play Integrity attestation should be compared against those added with `approov appsigncert`. The value of `setting` may be `on` or `off`. If turned `on` then the attestation is rejected if some `appsigncert` certificates have been added and none matched that provided from the attestation, as this would indicate the request did not appear to come from the expected app.
`-setRequireAppIntegrity <verdicts>`	Sets the list of \| seperated `verdicts` that are acceptable as an application integrity verdict. The possible values are provided here.
`-setRequireAppLicensing <verdicts>`	Sets the list of \| seperated `verdicts` that are acceptable as an app licensing integrity verdict. The possible values are provided here in terms of the `appLicensingVerdict` field.
`-setRequireDeviceIntegrity <verdicts>`	Sets the list of \| seperated `verdicts` that are acceptable as a device integrity verdict. The possible values are provided here. Note that you can opt-in in the Google Play console to potentially receive some additional verdicts.

Policy Command

approov policy [option]...

Option	Description
`-addRejectFlag <flag>`	Amends the rejection policy so that attestations will be rejected if the specified flag is set. Making a flag level modification such as this marks the rejection policy as `custom`. This requires an `admin` role.
`-get`	Gets the current security policy being applied to the account. This is provided as a comma separated string composed of the security rules, rejection policy and annotation policy as required by the `-set` option. More detailed information is also provided including a description of the impact of the current policy settings. The full list of flags, and whether they cause a rejection in the current policy, is also shown. The rejection policy is shown as `custom` if modifications have been made to the rejection status of individual flags. Note that it is also possible to get this with a `pentest` role.
`-getARC`	Gets the current ARC policy showing if issued Approov tokens will have an `arc` claim. This may be `on` or `off`. If ARC is `on` then the full list of flags that may be encoded by the value is shown.
`-getAudience`	Gets the current audience policy showing if issued Approov tokens will have an `aud` claim. This may be `on` or `off`.
`-getIPTracking`	Gets the current IP tracking setting for the account, which may be `token`, `full` or `none`.
`-getIssuedAt`	Gets the current issued-at policy showing if issued Approov tokens will have an `iat` claim. This may be `on` or `off`.
`-getIssuer`	Gets the current issuer policy showing if issued Approov tokens will have an `iss` claim. This may be `on` or `off`.
`-getSubject`	Gets the current subject policy showing if issued Approov tokens will have an `sub` claim. This may be `on` or `off`.
`-removeRejectFlag <flag>`	Removes the given flag from the set that causes a rejection. Making a flag level modification such as this marks the rejection policy as `custom`.
`-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: `security-rules`: Name of the overall security rules to be used, typically `default`. `rejection-policy`: Policy to be used to determine which preset rejection policy to use, determining which flags cause an invalid 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 `admin` role. It is actioned for production apps within 30 seconds.
`-setARC <policy>`	Sets the Attestation Response Code (ARC) policy to either being `on` or `off`. If the policy is enabled then all issued Approov tokens include an `arc` claim that provides an encoding of the device properties and whether an issued token was valid or not. This requires an `admin` role.
`-setAudience <policy>`	Sets the audience inclusion policy to either being `on` or `off`. If the policy is enabled then all issued Approov tokens include an `aud` claim providing the domain for which it was issued (or `*` for wildcard tokens). This may be used as an additional verification by the backend API. This requires an `admin` role.
`-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. This requires an `admin` role.
`-setIssuedAt <policy>`	Sets the issued-at inclusion policy to either being `on` or `off`. If the policy is enabled then all issued Approov tokens include an `iat` claim providing time at which the token was created. This requires an `admin` role.
`-setIssuer <policy>`	Sets the issuer inclusion policy to either being `on` or `off`. If the policy is enabled then all issued Approov tokens include an `iss` claim providing the account for which the token was issued. This may be used as an additional verification by the backend API. This requires an `admin` role.
`-setPinningTestURL <url>`	Enables the continuous pinning test and sets it to use the given `url`. This `url` should be something that it is possible to perform a successful `HTTP GET` operation with. Launched apps will check that the pinning mechanism prevents them from accessing this `url`; if they are able to, then the app is considered to be compromised. This option requires an `admin` role.
`-setSubject <policy>`	Sets the subject inclusion policy to either being `on` or `off`. If the policy is enabled then all issued Approov tokens include an `sub` claim providing the prefix `approov\|` and the device ID to which it was issued. This requires an `admin` role.

Registration Command

approov registration [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/watchOS or `.apk` / `.aab` for 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 appropriate app signing certificates need to have been added. The option `-playSigned` must be used if registering an Android `.apk` that is being signed by the Google Play store prior to release. Note that this option can also be performed using the `automation` role.
`-addFromDevice <device-ID>`	Adds (or updates) an app registration using information captured on the given `device-ID`. This allows a registration to be added if the original app package file is no longer available. Note that information must have been captured for the `device-ID`, which typically means it must have been setup as a custom device. For Android the `-playSigned` option can be used to indicate that the app was released using Google Play signing, in which case the app signing certificate must also be added using `approov appsigncert`.
`-appex`	This may be provided in conjunction with the `-add` option when registering an iOS IPA. This indicates that any app extensions associated with the package should also be registered.
`-bitcode`	This may be provided in conjunction with the `-add` option when registering an iOS IPA, if the SDK used supports bitcode. This indicates that the app is using bitcode, and is only necessary if the SDK has not been previously marked as using bitcode.
`-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.
`-checkSigType <app-path>`	Checks the signature type of the Android `.apk` app with the given `app-path`. This checks if the APK has been signed with a V2 or later signature scheme that allows it to be used with the `approov appsigncert` app signing certificates.
`-cloneToAccounts <accounts>`	Clones permanent app registrations to each of the comma seperated target `accounts`. The clone is made from the account of the currently active role. Each of the target accounts must have a `delegate` role initialized into the Approov CLI. Note that this also deletes any registrations in the target accounts that were previously cloned from the account of the currently active role but whose registrations have since been removed.
`-cloneToAllDelegateAccounts`	Clones permanent app registrations to all accounts that have a `delegate` role initialized. The clone is made from the account of the currently active role. Note that this also deletes any registrations in the target accounts that were previously cloned from the account of the currently active role but whose registrations have since been removed.
`-expireAfter <duration>`	This may be used in conjunction with the `-add`, `-addFromDevice` or `-updateExpiry` options 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 `admin` role. 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 longer expiry time between its current one and the new one being set. 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.
`-playSigned`	Indicates that, for an Android app, it is signed by Google Play prior to be released to the store. This is always the case with an Android App Bundle but it is also possible to release an APK in this way. You must use this option if so to indicate this and also add the app signing certificate using the `approov appsigncert` option. If you fail to do this then your app installed from the Play store will be marked as `app-not-registered` and valid Approov tokens will not be issued.
`-remove <signature>`	Removes the app registration with the given `signature`. The signature is the first contiguous string for the app registration obtained with the `-list` option. A partial signature may be used if it represents a unique prefix for all those that are available. Note the removal process assigns an expiry time for the registration two minutes into the future, at which point it is actually removed. Note that permanent app registrations can only be removed with an `admin` role or with a `dev` role belonging to the same user that originally registered 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 `admin` role is required to use this option.
`-unversioned`	This option may be used in conjunction with `-add` to create a registration that is not specific to any particular version of the app. Any app, signed by the same authority, with the same package name will be considered to be a valid registration. This means that you do not need to do a new app registration for each new version of the app released. However, this means that you lose the flexibility to remove registrations for specific (perhaps older) versions of your app. Note that this is not supported for Android `.apk`s, only for `.aab`s.
`-updateExpiry <signature>`	Updates the expiry time of the registration with the given `signature`. The signature is the first contiguous string for the app registration obtained with the `-list` option. A partial `signature` may be used if it represents a unique prefix for all those that are available. By default this will make the `signature` permanent, but the `-expireAfter` option may be used to specify a particular expirty time. Note though that this command may only be used to extend the expiry of an existing registration, not to shorten it.
`-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.
`-watchOS`	This option may be used in conjunction with `-add` for a `.ipa` to indicate that the registration is for a watchOS app embedded within the overall iOS app. If this option is used then only the watchOS app is registered, not the overall iOS app.

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.

SafetyNet Command

approov safetynet [option]...

Note that the safetynet command (apart from -get) requires the use of an admin role. A delegate role 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 [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` role. An example `curl` command is provided to verify access to the primary Approov servers. This command should generate a `HTTP 200` response.
`-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, if bitcode is supported for the library. Bitcode is no longer available from version 3.2.0 of the SDK or later. We suggest you use the default native version where possible for enhanced security. The bitcode version is available when a bitcode release is mandatory for your project. Obtaining this version of the SDK will automatically adjust the security settings to add bitcode mode for the SDK.
`-bitcodeAdd <ID>`	Marks the given SDK `ID` as being used in bitcode mode, if that version of the SDK supports bitcode. This means that it will be valid to the Apple App store using bitcode and using the particular SDK. This may only be applied to SDKs that support bitcode. An error is reported if the provided SDK `ID` does not support bitcode.
`-bitcodeList`	Lists all of the SDKs that have been marked as being used in bitcode mode. This is required for iOS applications where the submission to the App store is using bitcode.
`-bitcodeRemove <ID>`	Removes the given SDK `ID` as being used in bitcode mode. Note that this change has an immediate effect and if you have previously submitted to the Apple App store with that SDK then you may start to see Approov token faulures.
`-getClientPackage <pathname>`	Gets the client package specified with `-packageID` and writes it to the given `pathname`.
`-getConfig <pathname>`	This obtains the latest extended initial configuration string for the account and saves it to the given `pathname`. This file must be integrated into the mobile app and used to initialize the Approov SDK. Typically this option is only used if pins must always be available on initialization, otherwise the `-getConfigString` option is preferred. This option is also valid with a `delegate` or `automation` role.
`-getConfigOptions`	Obtains the list of configuration options that have been applied to the SDK. This enables individual features that must be setup on SDK initialization, before any Approov fetching has been performed.
`-getConfigString`	This obtains the latest short initial configuration string for the account. This can then be copied and pasted to provide the `initialConfig` for the SDK initialization. This option is also valid with a `delegate` or `automation` role.
`-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`, `.framework`, `.xcframework` (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`, `-simulator` or `-libraryID` options. This option is also valid with a `automation` role.
`-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.
`-list`	Lists all of the available SDK libraries, with their library ID, version number, and compatible platform. Note that, unless you have a specific reason you should use the version that is automatically selected when you use `-getLibrary`.
`-packageID <ID>`	Used in conjunction with the `-getClientPackage` option to specify which particular package `ID` should be downloaded.
`-setConfigOptions <options>`	Sets the list of configuration options that should be applied to the SDK. A comma separated list of string `options` should be provided. This is to enable individual features that must be setup on SDK initialization, before any Approov fetching has been performed.
`-simulator`	This can be used in conjunction with the `-getLibrary` option when getting an iO/watchOS SDK in either `.zip` or `.framework` format. Use of this option causes a different SDK package to be obtained for running on a simulator (without this option, the `-getLibrary` option retrieves an SDK that only works successfully on hardware devices). By default the SDK obtained is for iOS, use `-watchOS` if this is required.
`-watchOS`	This can be used in conjunction with the `-getLibrary` option to obtain a watchOS SDK library.

Secret Command

approov secret [option]...

Note that the secret command requires the use of an admin role.

These commands relate to the default account secret key. You may also add additional keys using the keyset commands and configure specific API domains to issue tokens signed or encrypted with the keys defined in that set instead.

Option	Description
`-change`	This causes the account secret key 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 account 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 new JWS tokens signed with the account secret.
`-forcePrintable`	This may be used in conjunction with the `-change` option to force the new account 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 account secret key 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. If the `-plain` option is used then only the account secret key is output by the command, allowing the output to be easily piped to other shell operations. If the `-jwe` option is used then the account secret key used to encrypt JWE tokens is obtained instead. The binary secret itself is always 64 bytes (512-bits) in length. It should be integrated into your backend to check the validity of Approov tokens. Note that the secret should be secured with the utmost care, since it allows valid Approov tokens of arbitrary lifetime to be generated. The account secret key itself should never be included in the mobile app or any software in the public domain.
`-getJWK <pathname>`	This gets the account secret key in the JSON Web Key (JWK) format and writes it to the specified `pathname`. This may be an easier for integration with those backend systems which support this format.
`-getJWKS <pathname>`	This gets the account secret key in the JSON Web Key Set (JWKS) format and writes it to the specified `pathname`. This may be easier for integration with those backend systems which support this format.
`-getKeyID`	Gets the optional key ID that was previously set for the account (using the `-setKeyID` option). If a key ID is set, then it appears in the `kid` field in all Approov token JWS headers that are signed using the account secret key.
`-jwe`	Can be used in conjunction with the `-get` to obtain the secret used to encrypt and sign JWE tokens.
`-messageSigningKey <operation>`	This manages the message signing key for the account with `operation` options as follows: `get-base64`: Gets the message signing secret encoded in base64 format. `get-base64url`: Gets the message signing secret encoded in base64url format. `get-raw`: Gets the message signing secret in its raw form (which is always printable). `change`: Changes the message signing secret to a new randomized value, enabling it if it wasn't previously. `clear`: Clears the message signing secret so the facility is no longer available. The binary secret itself is always 64 bytes (512-bits) in length. It is used to calculate the HMAC of an arbitrary message input and therefore provides an additional level of integrity checking for all request messages signed in this way. The Approov token should always be included as part of the signed message and transmitted alongside the signature.
`-plain`	Can be used in conjunction with the `-get` option to remove all text except the secret that may normally be output by the command. This may be useful when piping the output to other shell commands.
`-setKeyID <kid>`	This sets the specific `kid` to become the label for the account 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` or `-getJWKS`. Note that this only impacts tokens using the account secret key. Any tokens issued using a `keyset` key will contain that key's identifier instead.

Secure Strings Command

approov secstrings [option]...

Option	Description
`-addKey <key>`	Adds a new predefined string value with the given `key`. The `-predefinedValue` option must be used as well to define the value. This either writes a new key/value pair or overwrites an existing one. The maximum number of key/value pairs that may be defined is 16. There is also a 8KB limit on the total storage used for all key/value pairs. Key names cannot be longer than 64 characters. An `admin` role is required to perform this operation.
`-get`	Gets the current state of the secure strings feature.
`-predefinedValue <value>`	This is used in conjunction `-addKey` to define a new predefined key/value pair.
`-removeKey <key>`	Removes the predefined secure string with the given `key`. An `admin` role is required to perform this operation.
`-setDisabled`	Disables the secure strings. Subsequent attempts to fetch a secure string from the app will result in a `REJECTED / rejected` error. An `admin` role is required to perform this operation.
`-setEnabled`	Enables the use of the secure strings feature. An `admin` role is required to perform this operation.

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

Token Commands

approov token [option]...

Option	Description
`-check <token>`	Checks the validity of the provided `token` value. This shows if the token is valid or not and also decodes the contents of the token, including the algorithm and any key ID used. This works with either JWS or JWE Approov tokens. If a JWS token has expired then that is reported. If the token contains an ARC claim then that is decoded. Note that a LoggableToken may be provided, in which case its validity may be checked, unless the algorithm used is `PS256`, `PS384`, `PS512`, `ES256`, `ES384` or `ES512`.
`-genExample <domain>`	Causes an example Approov token to be generated for the given `domain`. The provided domain must already be registered as an API. The generated 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 will be generated when required by the configuration of the selected API domain. The token will include typical example claims. A data hash `pay` claim may be added using the `-SetDataHashInTokenOption`. Note that it is also possible to use this option with a `pentest` role.
`-genLongLived <params>`	This generates a long lived Approov token that is valid for the specified 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. This may only issue HS256 tokens issued with the account secret key. 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` role.
`-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 account secret key and provides an Approov token that represents a rejection. `valid`: Produces a valid token (the default)
`-showArcInfoCurl`	Displays the `curl` command that may be used to decode Attestation Response Codes (ARC). Note that, although the output is a `curl` command, you can of course use an alternative tool or command to perform the `GET` request.
`-showTokenInfoCurl`	Displays the `curl` command that may be used to get more information about an issued Approov token (and to report misuse). Any HTTP request providing the same parameters as the Curl command will get the same response.

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 behaviour 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.

Web Command

approov web [option]...
approov web <integration> [option]...

These commands may take a further optional subcommand to select the particular web integration that is being managed. The options for the integration are -fingerprint, -hcaptcha or -recaptcha.

Note that commands which modify the web configuration state need an admin role.

These are the commands to manage the overall integration.

Option	Description
`-list`	Lists the information about any web integrations. This also provides the site key that must be used in calls to obtain an Approov token from your web site.
`-setTokenLifetime <duration>`	Sets the Approov token lifetime (in seconds) for those tokens issued as part of a web integration. The default value is 120s.
`-setRefreshTokenLifetime <duration>`	Sets the refresh token lifetime (in seconds) for web integrations. The default refreshTokenLifetimeSecs is 2 hours (7200s).

These are the commands to manage any Fingerprint integration, of the form:

approov web -fingerprint [option]...

Option	Description
`-add <public-API-key>`	Adds a new Fingerprint subscription with the given `public-API-key`. The `-secret` and `-region` options must also be specified. This option may also be used to update the parameters associated with an existing subscription.
`-secret <secret>`	Specify the secret API key issued by Fingerprint to check the validity of a fingerprint. This must be specified if the `-add` option is used.
`-embedResult`	This may be specified with the `-add` option to include the full Fingerprint result whenever an encrypted Approov token is generated. By default only the Fingerprint `visitorId` is provided. An encrypted Approov token is generated when the target API is added using the `-jwe` flag, or when it uses a JWK with a signing method that uses encryption.
`-list`	Lists the information about the Fingerprint integration, including all of the subscriptions added.
`-maxBotProbability <score>`	This may be optionally used in conjunction with `-add` to specify the maximum probability of the browser instance being classified as a bot. The provided probability must be below the specified `score` for a valid Approov token to be issued. The default, if this option is not used, is 1.0.
`-maxElapsedTime <duration>`	This may be optionally used in conjunction with `-add` to specify the maximum elapsed time between the Fingerprint fingerprinting operation and the attempt to fetch an Approov token. We expect, under normal circumstances, for these operations to happen very closely together in time so any significant delay may be an indication of automation. The `duration` is specified in seconds, and decimal values are valid. The default, if this option is not used, is 2.0 seconds.
`-maxResultLifetime <duration>`	This can be used optionally with the `-add` option to specify the maximum lifetime for a Fingerprint result in seconds (the default of 0 seconds indictes that the result lifetime should be the same as the refresh token lifetime). The maximum lifetime cannot exceed the refresh token lifetime.
`-rateLimit <limit>`	This may be optionally used in conjunction with `-add` to specify the maximum number of requests per minute. Attempts to make requests beyond the limit will result in an error. The `limit` is specified in terms of the maximum number of requests per minute. If this is not specified then no limit is imposed. The limit can be removed by specifying 0 as the `limit`.
`-region <region>`	This must be provided with the `-add` to specify the region for the subscription. Valid values for `region` are `EU`(Europe) and `RoW`(Rest of the World).
`-remove <public-API-key>`	Removes any subscription associated with the given `public-API-key`.
`-setOptional`	Makes the use of Fingerprint optional, allowing an Approov token to be provided for a web protection via another integration even if a Fingerprint result is not provided. This is the default when the Fingerprint integration is first added.
`-setRequired`	Makes the use of Fingerprint a requirement. This means that in order to obtain an Approov token via web protection a Fingerprint result must always be submitted.

These are the commands to manage any hCaptcha integration, of the form:

approov web -hcaptcha [option]...

Option	Description
`-add <site-key>`	Adds a new hCaptcha site with the given `site-key`. The `-secret` option must also be specified. This option may also be used to update the parameters associated with an existing site.
`-domain <domain>`	Specify the `domain` of a site to be protected with hCaptcha where a web protection is to be performed. Note that this option may be used multiple times for a given site to specify multiple domains.
`-embedResult`	This may be specified with the `-add` option to include the full hCaptcha result whenever an encrypted Approov token is issued. By default only the `challenge_ts` and `hostname` properties are provided. An encrypted Approov token is generated when the target API is added using the `-jwe` flag, or when it uses a JWK with a signing method that uses encryption.
`-includeIP`	This may be specified with the `-add` option to force the IP of the client to be included when performing the hCaptcha verification. If this option is not specified then the IP is not included.
`-list`	Lists the information about the HCaptcha integration, including all of the sites added.
`-minScore <score>`	This may be optionally used in conjunction with `-add` to specify the minimum acceptable score for the hCaptcha. The computed value must be above the specified `score` for a valid Approov token to be issued. The default, if this option is not used, is 0.0.
`-maxResultLifetime <duration>`	This can be used optionally with the `-add` option to specify the maximum lifetime for a Fingerprint result in seconds (the default of 0 seconds indictes that the result lifetime should be the same as the refresh token lifetime). The maximum lifetime cannot exceed the refresh token lifetime.
`-rateLimit <limit>`	This may be optionally used in conjunction with `-add` to specify the maximum number of requests per minute. Attempts to make requests beyond the limit will result in an error. The `limit` is specified in terms of the maximum number of requests per minute. If this is not specified then no limit is imposed. The limit can be removed by specifying 0 as the `limit`.
`-remove <site-key>`	Removes any site associated with the given `site-key`.
`-secret <api-key>`	This must be used in conjunction with the `-add` option to set the secret `api-token` that is used to check the validity of the hCaptcha.
`-setOptional`	Makes the use of hCaptcha optional, allowing an Approov token to be provided for a web protection via another integration even if a hCaptcha result is not provided. This is the default when the HCaptcha integration is first added.
`-setRequired`	Makes the use of hCaptcha a requirement. This means that in order to obtain an Approov token via web protection a hCaptcha result must always be submitted.

These are the commands to manage any reCAPTCHA integration, of the form:

approov web -recaptcha [option]...

Option	Description
`-action <action>`	This may be used in conjunction with `-add` to specify a valid `action` to be used for the domains associated with the site. Note that multiple actions may be specified. If no actions are specified at all then any may be specified.
`-add <site-key>`	Adds a new reCAPTCHA site with the given `site-key`. The `-secret` option must also be specified. This option may also be used to update the parameters associated with an existing site.
`-domain <domain>`	Specify the `domain` of a site to be protected with reCAPTCHA where a web protection is to be performed. Note that this option may be used multiple times for a given site to specify multiple domains.
`-embedResult`	This may be specified with the `-add` option to include the full reCAPTCHA result whenever an encrypted Approov token is issued. By default only the `challenge_ts` and `hostname` properties are provided. An encrypted Approov token is generated when the target API is added using the `-jwe` flag, or when it uses a JWK with a signing method that uses encryption.
`-includeIP`	This may be specified with the `-add` option to force the IP of the client to be included when performing the reCAPTCHA verification. If this option is not specified then the IP is not included.
`-list`	Lists the information about the reCAPTCHA integration, including all of the sites added.
`-minScore <score>`	This may be optionally used in conjunction with `-add` to specify the minimum acceptable score for the reCAPTCHA. The computed value must be above the specified `score` for a valid Approov token to be issued. The default, if this option is not used, is 0.0.
`-maxResultLifetime <duration>`	This can be used optionally with the `-add` option to specify the maximum lifetime for a Fingerprint result in seconds (the default of 0 seconds indictes that the result lifetime should be the same as the refresh token lifetime). The maximum lifetime cannot exceed the refresh token lifetime.
`-rateLimit <limit>`	This may be optionally used in conjunction with `-add` to specify the maximum number of requests per minute. Attempts to make requests beyond the limit will result in an error. The `limit` is specified in terms of the maximum number of requests per minute. If this is not specified then no limit is imposed. The limit can be removed by specifying 0 as the `limit`.
`-remove <site-key>`	Removes any site associated with the given `site-key`.
`-secret <api-key>`	This must be used in conjunction with the `-add` option to set the secret `api-token` that is used to check the validity of the reCAPTCHA.
`-setOptional`	Makes the use of reCAPTCHA optional, allowing an Approov token to be provided for a web protection via another integration even if a reCAPTCHA result is not provided. This is the default when the reCAPTCHA integration is first added.
`-setRequired`	Makes the use of reCAPTCHA a requirement. This means that in order to obtain an Approov token via web protection a reCAPTCHA result must always be submitted.

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

Table of Contents

Approov CLI Reference

Overview

API Command

AppAttest Command

App Signing Certificates Command

Custom JWT Command

Device Command

DeviceCheck Command

Filter Command

ForceFail Command

ForcePass Command

Init Command

Keyset Command

Monitoring Command

Metrics Command

Password Command

Pin Command

Play Integrity Command

Policy Command

Registration Command

Role Command

SafetyNet Command

SDK Command

Secret Command

Secure Strings Command

Support Command

Token Commands

Users Command

Web Command

Whoami Command