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, init, keyset, metrics, monitoring, password, pin, 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 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 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 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 admin or delegate role is required to perform this operation.

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 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-did 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.
-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. Note that if the device is running an app with a 2.9.0 or later Approov SDK then it is not possible to get individual device state.
-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-did then information is provided for up to 100 of the most recent new devices IDs 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.
-newDIDOnly 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.
-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%. 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.

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

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

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.
-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.
-getIssuer Gets the current issuer policy showing if issued Approov tokens will have an iss 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.
-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.
-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.
-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.

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 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 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.
-bitcode This may be provided in conjunction with the -add option when registering an iOS IPA. 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.
-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 .apks, only for .aabs.
-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.

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. 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. This means that it will be valid to the Apple App store using bitcode and using the particular SDK.
-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.
-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.
-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 iOS SDK in either .zip or .framework format. Use of this option causes a different SDK package to be obtained for running on an iOS simulator (without this option, the -getLibrary option retrieves an iOS SDK that only works successfully on hardware devices).

Secret Command

approov secret [option]...

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

These commands relate to the account secret key used by default. You may also add additional keys using the keyset commands and set specific API domains to issue tokens signed or encrypted with the keys defined there 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 <browser-token> Adds a new Fingerprint subscription with the given browser-token. The -apiToken and -region options must also be specified. This option may also be used to update the parameters associated with an existing subscription.
-apiToken <secret> Specify the secret API token 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 <browser-token> Removes any subscription associated with the given browser-token.
-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