Skip to main content

Managing API Domains

This provides an overview of the management of API domains in the account. These correspond to the domains for which Approov protection can be applied.

Overview​

Each Approov account has a set of API domains for which an app can fetch Approov tokens. These will typically correspond to the domains serving the APIs that are to be protected with Approov. An account may have a maximum of 25 different domains. API domains may be added and removed from the account as required.

Approov is passed the API domain for which a token is being fetched. There are a couple of motivations for specifying Approov token fetches with particular domains:

  • APIs that are protected with Approov tokens need to be pinned to prevent a Man-in-the-Middle (MitM) attack from stealing valid, albeit short lived, Approov tokens. Pinning needs to be based on the domain for the API since this determines the certificate that will be presented by the server.
  • It is possible that Approov tokens fetched for different domains are in a different format, or are signed using different secret keys. For instance, a particular domain may be setup to use encrypted (JWE) rather than symmetrically signed (JWS) tokens.

Domains are restricted to lower and upper case letters, digits, a dash and a period. This means that the API domain should not (and cannot) contain the full URI path to a particular resource.

There is no special handling of sub-domains so, for instance, your.domain and sub.your.domain are considered to be entirely distinct.

Adding API Domains​

A new API domain can be added to the account as follows:

approov api -add your.domain

Confirmation is required whenever a new domain is added. This is because it has an immediate impact in production, with tokens being served for the new domain. As soon as a domain is added, tokens for the API domain can be obtained.

using managed trust roots rather than pinning to protect the API channel
WARNING: adding the API will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
added API domain your.domain with type:account, alg:HS256, pin:JG29gD8vWiEanTCVPjYLQ5yiYMKQqR05OH38yFf0kBU=
enabled continuous monitoring for https://your.domain:443 (remove using `approov monitoring -removeAPI`)

An error is generated if the provided domain is not accessible from your local machine, and in this situation you will have to confirm addition. If the API domain is not on the standard port 443, you can use the -port option to select a different port. Do not try and add the port to the API domain name itself as this is not valid.

By default, newly added domains are included for continuous API monitoring. This means that you will receive an email notification if the API domain becomes inaccessible or the certificates it presents are no longer valid. Note that you must setup the alert email or general email recipients to receive these notifications.

By default, newly added domains will support attestations from mobile apps. Add the -allowWeb flag if you also need to provide access to the API from web apps using one or more of the Web Protection Integration.

By default, Approov tokens for a particular API will be issued as signed JWS tokens using the account secret key. Approov also provides an option to issue encrypted JWE tokens for a domain. This is enabled by using the -jwe option when adding the new API domain. See Approov token format for more details.

tip

Once you have added an API domain you can edit its attributes by adding it again with the new set of attribute options specified. However, editing an API domain requires the admin role.

Keyset Key API Addition​

If you have added one or more keyset keys then you can add an API domain that uses one of those keys as follows:

approov api -add your.domain -keySetKID your-key

This requires confirmation as follows:

using managed trust roots rather than pinning to protect the API channel
WARNING: adding the API will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
added API domain twitter.com with type:keyset, alg:RS256, kid:your-key, pin:kJ8+U7wNPfc5vxwnQYvlffbaZA6wwCvd/eC8YMpB+sU=
enabled continuous monitoring for https://your.domain:443 (remove using `approov monitoring -removeAPI`)

This adds the domain using the keyset key your-key. This means that all Approov tokens issued for the domain will be signed or encrypted with the specified key. The key identifier will appear in the kid claim in the header. The particular algorithm to be used is also defined by the key, allowing a wide range of choices including asymmetric options which can ensure that the Approov cloud service is the only entity capable of generating valid tokens signed with the private key, which the tokens can be verified by your backend using the public key.

Adding No Approov Token Domains​

An option is provided to add an API domain which does not need Approov tokens to be sent. Do this as follows:

approov api -add your.other.domain -noApproovToken

This requires confirmation as follows:

using managed trust roots rather than pinning to protect the API channel
WARNING: adding the API will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
added API domain your.other.domain with type:none, pin:kJ8+U7wNPfc5vxwnQYvlffbaZA6wwCvd/eC8YMpB+sU=
enabled continuous monitoring for https://your.other.domain:443 (remove using `approov monitoring -removeAPI`)

The purpose of this is to allow access to the pinning or managed trust root features of Approov without the need to send Approov tokens. This option should therefore only be used on endpoints where it is not necessary or possible to add Approov token checking on the backend.

Any attempt to get a token for the domain results in an UNPROTECTED_URL / unprotectedURL status from the Approov token fetch call. The Mobile App Quickstarts continue with the request in this case without adding an Approov token.

Listing API Domains​

A list of all the domains that are configured for the account can be obtained with:

approov api -list

This provides information about all of the domains that have been added and their attributes:

2 API domains:
 your.domain           type:account, alg:HS256
 shapes.approov.io  type:restricted, alg:HS256

The type attribute may be:

  • account: This is the default, indicating that the account secret key is used.
  • restricted: Indicates that the keys and pins for the domain are centrally managed by Approov.
  • keyset: Indicates that the key used for the domain is one from the keyset.
  • none: Indicates that the domain has been added without the need to send Approov tokens.

The alg attribute shows the type of algorithm used for signing or encrypting the Approov tokens. By default, for account type tokens, the HS256 signing algorithm is used. However, if the -jwe option was used then the A256GCMKW JWE encryption algorithm is used instead. For a keyset type a wider range of algorithms are available.

The kid attribute, and the associated value, is shown if the domain has been configured to use a JWT KeySet entry. The specified key ID will be included in the header of all subsequent tokens issued for the domain.

The monitorPort property is included if continuous monitoring has been enabled for the domain (the default). This displays the port being used to probe the domain, normally 443. (See API Monitoring)

Approov tokens are only served, for an account, for those APIs listed by this command. Any attempt to get a token for another domain results in an UNKNOWN_URL / unknownURL error from the Approov token fetch call (unless wildcard mode is enabled).

Removing API Domains​

An API domain that has been previously added can be removed with the following command:

approov api -remove your.domain

Note that removal of an API domain requires an admin role and further confirmation is required before the domain is removed:

WARNING: removing the API will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
removed API domain your.domain

Once removed this means that Approov tokens will no longer be served for that domain. You must not remove a domain that is being used by production apps as this will lead to a production outage.

Setting Wildcard Mode​

A facility is provided to enable wildcard Approov tokens. Normally if a token fetch is made for a domain for which an API domain has not been added, then an UNKNOWN_URL / unknownURL error is returned. In typical Approov SDK usage this will cause the API request to continue without adding an Approov token. If wildcard tokens are enabled then an Approov token will be returned always. However, if the URL is not for an explicitly added API domain then the provided Approov token will always be a failing one. This is because these domains will not be pinned and so valid Approov tokens should not be transmitted on them.

The purpose of this mode is to enable quick discovery of which particular API calls are getting Approov tokens added and to manually check if Approov tokens are being received at the backend, prior to implementing full backend Approov token checking. A gradual transition to full Approov protection can then be made, by adding API domains and turning off wildcard mode without any need to make code changes to the app.

Wildcard token mode can be enabled as follows:

approov api -setWildcardMode on

It may be subsequently disabled using an off parameter value.

The current wildcard status can be found with:

approov api -getWildcardMode

Adding Demonstration Shapes API​

A special shapes domain (managed by the Approov team) can be added to your account:

approov api -add shapes.approov.io

Confirmation will be required as follows:

WARNING: adding the API will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
added API domain shapes.approov.io with type:restricted, alg:HS256

This domain serves a very simple API that provides random shapes and it is used by the Approov demo app. Any account can add this domain to generate Approov tokens for the API. The type is shown as restricted meaning that it has the special property that the associated Approov tokens with a secret key expected by that API rather than the standard one for the account. Moreover, you are not able to modify the pins associated with that domain.