Approov CLI Tool Reference

Overview

The Approov command line tool is used for administering the operation of your Approov service. Builds of the tool are available for Linux, MacOS and Windows. 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, appsigncert, device, devicecheck, filter, init, keyset, metrics, monitoring, password, pin, policy, registration, role, safetynet, sdk, secret, token, users 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 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 -pinOnly 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.
-check Checks all of the API domains to ensure that they are both accessible and that the pins specified match at least one certificate in the chain. The certificate chain is obtained via a local network access. This command can be used in a periodic check script to generate some kind of alert if the pins are incorrect and may be causing app failures in production.
-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.
-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 -pinOnly. 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 -pinOnly.
-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.
  • pinOnly: Indicates that no Approov tokens are being sent for the domain (added for pinning only).
  • restricted: Indicates that Approov has automatically assigned the algorithm and keys for the domain.
-pinOnly Can be used in conjunction with the -add option to specify that the API domain being added is only for protection by Approov pinning and no Approov token is required. 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 on additional domains that do not require the use of Approov tokens. Should not be used with -keySetKID 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.

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.

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.
-getDeviceState <device-ID> Gets any persisted state for the given device-ID. In particular this provides information about the DeviceCheck or SafetyNet state for a device, or any banning that has been applied to it. The device-ID is a base64 encoded identification string that can be obtained from logging on the device or from the did claim in an Approov token generated on the device.
-getFetches <timing> Gets the device IDs of up to the most recent 1000 that have requested Approov tokens for the account. If the timing parameter is timed then the timestamp of the request is shown. It is not present if untimed is used.
-getInfo <device-ID> Gets detailed information about the given device-ID if it has been previously added as a custom device using -add and it has made a token fetch since then. The time of the information capture is shown. The information provided may be used by the filter commands. If device-ID is specified as new-did then information is provided for up to 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 the devicecheck command (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 device check information.
-remove Removes the device check information from the account.
-teamID <ID> This option must be used in conjunction with -addAuthKey and specifies the team identifier for your apps. This identifies apps as being issued by your team and is required in order to make calls to Apple APIs to get and update the device check bits.

Filter Command

approov filter [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 token 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 token 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.
<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.
<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.

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 getting the -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.
-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 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 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.
-remove <email> Removes the given email address from the list of those to receive account activity summaries.
-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 token fetches on those apps and the implementation should ensure that pin bindings are updated at the earliest convenience.
-getCertChainPins Obtains the public key pins for the certificate chain for the domain specified with -api. The leaf certificate is shown first and then the chain right up to the root certificate. The public key pin, expiry date and subject information is provided for each element in the chain. This can be used to obtain the pins for intermediate certificates.
-getCertPin <file> Extracts the public key pin for the certificate provided in the given file. This must be a base64 encoded PEM certificate. This can be used for obtaining the pin for a certificate that has not yet been put into active usage. The expiry date and subject information is also provided. Note that no -api is required.
-getLeafPin <type> Obtains the public key pin for the leaf certificate at the domain specified with -api. The type specifies the pin extraction requirement and may one of:
  • matching: Check local and remote pins and ensure they match.
  • local: Extract the pin as observed via local network access.
  • remote: Extract the pin as observed by the Approov servers,
-list Lists all of the pins associated with the API domain specified with -api.
-port <number> If -getLeafPin 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.

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.
-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.
-getPinningTestURL Gets the test URL that has been specified for continuous pinning testing to help ensure it has not been compromised.
-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.
-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. 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. Note that this option can also be performed using the automation role.
-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 option to set a temporary period for a registration. By default, a registration is permanent, and this means that it can only be removed using an 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.
-remove <signature> Removes the app registration with the given signature. This corresponds to the first contiguous string for the app registration obtained with the -list option. Any removal of the registration will have an impact on production apps within 30 seconds. Note that permanent app registrations can only be removed with an 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.
-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 enable use of bitcode.
-getConfig <pathname> This obtains the latest initial configuration string for the account and saves it to the given file. This file must be integrated into the mobile app and used to initialize the Approov SDK. This option is also valid with a delegate 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 token fetching has been performed.
-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 token fetching has been performed. Note that you should obtain a new initial configuration when the options have been changed.
-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.

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

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