Token Fetch

Fetch Result

Java

/**
 * Potential status results from an attempt to fetch from the SDK
 */
public enum TokenFetchStatus {
        SUCCESS,                // fetch was completed successfully
        NO_NETWORK,             // fetch failed because there is no network connectivity currently
        MITM_DETECTED,          // fetch failed because there is a Man-In-The-Middle (MITM) to the Approov cloud service
        POOR_NETWORK,           // fetch failed due to poor network connectivity
        NO_APPROOV_SERVICE,     // fetch failed, perhaps because Approov services are down
        BAD_URL,                // provided URL was not https or otherwise in the correct format
        UNKNOWN_URL,            // provided URL is not one that one configured for Approov
        UNPROTECTED_URL,        // provided URL does not need an Approov token
        NO_NETWORK_PERMISSION,  // app does not have ACCESS_NETWORK_STATE or INTERNET permission
        MISSING_LIB_DEPENDENCY, // app is missing a needed library dependency
        INTERNAL_ERROR,         // there has been an internal error in the SDK
        REJECTED,               // indicates a custom JWT or secure string fetch has been rejected because Approov attestation fails
        DISABLED,               // indicates that a custom JWT or secure string fetch fails because the feature is not enabled
        UNKNOWN_KEY             // indicates an attempt to fetch a secure string that has not been defined
    }

/**
 * Results from a fetch operation, including custom JWT and secure string fetches, as
 * well as standard Approov token fetches.
 */
public class TokenFetchResult {
  /**
   * Gets the status of the last fetch operation.
   *
   * @return Approov fetch status
   */
  public TokenFetchStatus getStatus();

  /**
   * Gets the token string of the last Approov token fetch. This may be an empty string
   * if the fetch did not succeed. This value should not not be cached by the app client
   * code.
   *
   * @return Approov token string
   */
  public String getToken();

  /**
   * Gets an optional base64url encoded traceID for the Approov token fetch which may be used to
   * assist with debugging.
   *
   * @return any traceID associated with the token fetch, or null if not available
   */
  public String getTraceID();

  /**
   * Gets the secure string of the last secure string fetch. This may be null if the
   * string is not available. This value should not not be cached by the app client
   * code.
   *
   * @return any secure string or null if not available
   */
  public String getSecureString();

  /**
   * Gets any Attestation Response Code (ARC) associated with the last fetch. This may be an empty string
   * if the fetch did not succeed or if ARC is not enabled.
   *
   * @return ARC string
   */
  public String getARC();

  /**
   * Gets any rejection reasons describing why Approov attestation has failed. This is
   * a comma separated list of device properties, or an empty string for a pass or if the
   * feature is not enabled.
   *
   * @return comma separated rejection reasons, or empty string otherwise
   */
  public String getRejectionReasons();

  /**
   * Determines if a new configuration is available from fetchConfig().
   *
   * @return true if an updated configuration is available
   */
  public boolean isConfigChanged();

  /**
   * Determines if current user APIs must be updated to reflect a new version
   * available from getPins() or getPinsJSON(). Calling getPins() or getPinsJSON() will
   * clear this flag for the next Approov fetch.
   *
   * @return true if pins should be updated
   */
  public boolean isForceApplyPins();

  /**
   * Gets a measurement configuration if the last token fetch was to perform an
   * integrity measurement and was successful.
   *
   * @return Approov measurement configuration or null if no measurement made
   */
  public byte[] getMeasurementConfig();

  /**
   * Gets a loggable version of the result Approov token. This provides the decoded JSON payload
   * along with the first six characters of the base64 encoded signature as an additional
   * "sip" claim. This can be safely logged as it cannot be transformed into a valid token
   * since the full signature is not provided, but it can be subsequently checked for validity
   * if the shared secret is known, with a very high probability. The loggable token is always
   * valid JSON. If there is an error then the type is given with the key "error". Note that
   * this is not applicable to JWE tokens.
   *
   * @return Loggable Approov token string
   */
  public String getLoggableToken();
}

Objective-C

/*
 * Enumeration of results that may be generated as a result of an Approov fetch operation.
 */
typedef NS_ENUM(NSUInteger, ApproovTokenFetchStatus)
{
    // Indicates that a fetch successfully completed.
    ApproovTokenFetchStatusSuccess,

    // Indicates that the fetch failed because there is currently no network connectivity.
    ApproovTokenFetchStatusNoNetwork,

    // Indicates that the fetch failed because the certificate presented on the Approov endpoint was not one
    // that was expected. This might indicate the device is running on a network with a firewall that terminates TLS.
    ApproovTokenFetchStatusMITMDetected,

    // Indicates that the fetch failed due to poor network connectivity.
    ApproovTokenFetchStatusPoorNetwork,

     // Indicates that the fetch failed, perhaps because Approov services (primary and failover) are down.
    ApproovTokenFetchStatusNoApproovService,

    // Indicates that the provided domain is not in the correct format or is not of the https scheme.
    ApproovTokenFetchStatusBadURL,

    // Indicates that the URL provided is a for a domain that has not be specified in the Approov administration portal.
    // This may be an incorrect URL or may indicate that no Approov token is required for protecting this endpoint.
    ApproovTokenFetchStatusUnknownURL,

    // Indicates that no Approov token is needed for the domain. This is returned as a result of a configuration
    // that is set server side, indicating that the domain is pinned but no Approov token is required.
    ApproovTokenFetchStatusUnprotectedURL,

    // Indicates that the Approov SDK has not been initialized.
    ApproovTokenFetchStatusNotInitialized,

    // Indicates a custom JWT or secure string fetch has been rejected because Approov attestation fails.
    ApproovTokenFetchStatusRejected,

    // Indicates that a custom JWT or secure string fetch fails because the feature is not enabled.
    ApproovTokenFetchStatusDisabled,

    // Indicates an attempt to fetch a secure string that has not been defined.
    ApproovTokenFetchStatusUnknownKey,

    // Indicates an attempt to fetch a secure string with a bad key.
    ApproovTokenFetchStatusBadKey,

    // Indicates an attempt to fetch a custom JWT with a bad payload.
    ApproovTokenFetchStatusBadPayload,

    // Indicates an internal SDK error.
    ApproovTokenFetchStatusInternalError
};

/**
 * This interface is used for the result value of the fetch methods.
 */
__attribute__((visibility("default"))) @interface ApproovTokenFetchResult: NSObject

// The result code generated by a fetch operation
@property (readonly) ApproovTokenFetchStatus status;

// The last fetched token as a string which should not be cached by the app client code. This is the empty string if
// no token could be obtained.
@property (readonly, nonnull) NSString *token;

// An optional base64url encoded traceID for the Approov token fetch which may be used to assist with debugging.
@property (readonly, nullable) NSString *traceID;

// The secure string of the last secure string fetch. This value should not be cached by the app client code. This
// may be nil if the string is not available.
@property (readonly, nullable) NSString *secureString;

// Any Attestation Response Code (ARC) providing details of the device properties. This is the empty string if
// no ARC was obtained.
@property (readonly, nonnull) NSString *ARC;

// Any rejection reasons describing why Approov attestation has failed. This is a comma separated list of
// device properties, or an empty string for a pass or if the feature is not enabled.
@property (readonly, nonnull) NSString *rejectionReasons;

// Provides a flag indicating if a new updated configuration JWT has been obtained from the server. Once set this
// remains true for subsequent token fetches until a fetchConfig() call is made.
@property (readonly) BOOL isConfigChanged;

// Provides a flag indicating if current user APIs must be updated to reflect a new version
// available from getPins(). Calling getPins() will clear this flag for the
// next Approov token fetch.
@property (readonly) BOOL isForceApplyPins;

// The measurement configuration is only provided if the last fetch operation for the domain initiated an integrity
// measurement, and the fetch was successful. This provides a binary buffer that must be provided to the
// getIntegrityMeasurementProof() or getDeviceMeasurementProof() to obtain a new proof.
@property (readonly, nullable) NSData *measurementConfig;

// ApproovTokenFetchCallback type definition
typedef void (^ApproovTokenFetchCallback)(ApproovTokenFetchResult *_Nonnull result);

/**
 * Gets a loggable version of the result Approov token. This provides the decoded JSON payload along with the first six
 * characters of the base64 encoded signature as an additional "sip" claim. This can be safely logged as it cannot be
 * transformed into a valid token since the full signature is not provided, but it can be subsequently checked for
 * validity if the shared secret is known, with a very high probability. The loggable token is always valid JSON. If
 * there is an error then the type is given with the key "error".
 * Note that this is not applicable to JWE tokens.
 *
 * @return Loggable Approov token string
 */
- (nonnull NSString *)loggableToken;

@end

/**
 * Gets a human readable string from an Approov token fetch status.
 *
 * @param approovTokenFetchStatus is the ApproovTokenFetchStatus
 * @return the string for the ApproovTokenFetchStatus
 */
+ (nonnull NSString *)stringFromApproovTokenFetchStatus:(ApproovTokenFetchStatus)approovTokenFetchStatus;

Swift

/*
 * // Enumeration of results that may be generated as a result of an Approov fetch operation.
 */  
enum ApproovTokenFetchStatus {
    // Indicates that a fetch successfully completed.
    case success  

    // Indicates that the fetch failed because there is currently no network connectivity.
    case noNetwork

    // Indicates that the fetch failed because the certificate presented on the Approov endpoint was not one
    // that was expected. This might indicate the device is running on a network with a firewall that terminates TLS.
    case mitmDetected

    // Indicates that no token could be obtained due to poor network connectivity
    case poorNetwork

    // Indicates that the fetch failed, perhaps because Approov services (primary and failover) are down.
    case noApproovService

    // Indicates that the provided domain is not in the correct format or is not of the https scheme.
    case badURL

    // Indicates that the URL provided is a for a domain that has not be specified in the Approov administration portal.
    // This may be an incorrect URL or may indicate that no Approov token is required for protecting this endpoint.
    case unknownURL

    // Indicates that no Approov token is needed for the domain. This is returned as a result of a configuration
    // that is set server side, indicating that the domain is pinned but no Approov token is required.
    case unprotectedURL

    // Indicates that the Approov SDK has not been initialized.
    case notInitialized

    // Indicates a custom JWT or secure string fetch has been rejected because Approov attestation fails.
    case rejected

    // Indicates that a custom JWT or secure string fetch fails because the feature is not enabled.
    case disabled

    // Indicates an attempt to fetch a secure string that has not been defined.
    case unknownKey

    // Indicates an attempt to fetch a secure string with a bad key.
    case badKey

    // Indicates an attempt to fetch a custom JWT with a bad payload.
    case badPayload

    // Indicates an internal SDK error.
    case InternalError
}

/**
 * This interface is used for the result value of the fetch methods.
 */
class ApproovTokenFetchResult: NSObject {

    // The result code generated by a fetch operation
    private(set) var status: ApproovTokenFetchStatus?

    // The last fetched token as a string which should not be cached by the app client code. This is the empty string if
    // no token could be obtained.
    private(set) var token = ""

    // An optional base64url encoded traceID for the Approov token fetch which may be used to assist with debugging.
    private(set) var traceID: String?

    // The secure string of the last secure string fetch.  This value should not be cached by the app client code. This may
    // be nil if the string is not available.
    private(set) var secureString: String?

    // Any Attestation Response Code (ARC) provided details of the device properties. This is the empty string if
    // no ARC was obtained.
    private(set) var arc = ""

    // Any rejection reasons describing why Approov attestation has failed. This is a comma separated list of
    // device properties, or an empty string for a pass or if the feature is not enabled.
    private(set) var rejectionReasons = ""

    // Provides a flag indicating if a new updated configuration JWT has been obtained from the server. Once set this
    // remains true for subsequent token fetches until a fetchConfig() call is made.
    private(set) var isConfigChanged = false

    // Provides a flag indicating if current user APIs must be updated to reflect a new version
    // available from getPins() or getPinsJSON(). Calling getPins() or getPinsJSON() will clear this flag for the
    // next Approov token fetch.
    private(set) var isForceApplyPins = false

    // The measurement configuration is only provided if the last fetch operation for the domain initiated an integrity
    // measurement, and was successful. This provides a binary buffer that must be provided to the
    // getIntegrityMeasurementProof() or getDeviceMeasurementProof() to obtain a new proof.
    private(set) var measurementConfig: Data?

    /**
     * Gets a loggable version of the result Approov token. This provides the decoded JSON payload along with the first six
     * characters of the base64 encoded signature as an additional "sip" claim. This can be safely logged as it cannot be
     * transformed into a valid token since the full signature is not provided, but it can be subsequently checked for
     * validity if the shared secret is known, with a very high probability. The loggable token is always valid JSON. If
     * there is an error then the type is given with the key "error".
     * Note that this is not applicable to JWE tokens.
     *
     * @return Loggable Approov token string
     */
    func loggableToken() -> String
}

/**
 * Gets a human readable string from an Approov token fetch status.
 *
 * @param approovTokenFetchStatus is the ApproovTokenFetchStatus
 * @return the string for the ApproovTokenFetchStatus
 */
class func string(from approovTokenFetchStatus: ApproovTokenFetchStatus) -> String

Synchronous Token Fetch

Java

/**
 * Initiates a synchronous request to obtain an Approov token and other results. If an Approov token fetch
 * has been completed previously and the tokens are unexpired then this may return the same one
 * without a need to perform a network transaction. Note though that the caller should never cache the
 * Approov token as it may become invalidated at any point.
 *
 * If a new Approov token is required then a more extensive app measurement is performed that involves
 * communicating with the Approov cloud service. Thus this method may take up to several seconds to
 * return and should not be called from a UI thread. There is also a chance that due to poor network
 * connectivity or other factors an Approov token cannot be obtained, and this is reflected in the
 * returned status.
 *
 * All calls must provide a URL which provides the endpoint of the API to which the Approov token is going
 * to be sent. Different host domains will have different Approov tokens associated with
 * them so it is important that the Approov token is only sent to requests for that domain. If the
 * domain has not been configured in the account then an error is obtained. Note that the provided
 * URL may be suffixed by "?measurement" to initiate a measurement process for use with integrity and
 * device proofs.
 *
 * @param url provides the URL for which a token is being fetched
 * @return results of fetching a token
 */
public static final TokenFetchResult fetchApproovTokenAndWait(String url);

Objective-C

/**
 * Initiates a synchronous request to obtain an Approov token and other results. If an Approov token fetch
 * has been completed previously and the tokens are unexpired then this may return the same one
 * without a need to perform a network transaction. Note though that the caller should never cache the
 * Approov token as it may become invalidated at any point.
 *
 * If a new Approov token is required then a more extensive app measurement is performed that involves
 * communicating with the Approov cloud service. Thus this method may take up to several seconds to
 * return and should not be called from a UI thread. There is also a chance that due to poor network
 * connectivity or other factors an Approov token cannot be obtained, and this is reflected in the
 * returned status.
 *
 * All calls must provide a URL which provides the endpoint of the API to which the Approov
 * token is going to be sent. Different host domains will have different Approov tokens associated with
 * them so it is important that the Approov token is only sent to requests for that domain. If the
 * domain has not been configured in the account then an error is obtained. Note that the provided
 * URL may be suffixed by "?measurement" to initiate a measurement process for use with integrity and
 * device proofs. Note that the provided URL may be suffixed by "?measurement" to initiate a measurement
 * process for use with integrity and device proofs.
 *
 * @param url provides the URL for which a token is being fetched
 * @return results of fetching a token
 */
+ (nonnull ApproovTokenFetchResult *)fetchApproovTokenAndWait:(nonnull NSString *)url;

Swift

/**
 * Initiates a synchronous request to obtain an Approov token and other results. If an Approov token fetch
 * has been completed previously and the tokens are unexpired then this may return the same one
 * without a need to perform a network transaction. Note though that the caller should never cache the
 * Approov token as it may become invalidated at any point.
 *
 * If a new Approov token is required then a more extensive app measurement is performed that involves
 * communicating with the Approov cloud service. Thus this method may take up to several seconds to
 * return and should not be called from a UI thread. There is also a chance that due to poor network
 * connectivity or other factors an Approov token cannot be obtained, and this is reflected in the
 * returned status.
 *
 * All calls must provide a URL which provides the endpoint of the API to which the Approov
 * token is going to be sent. Different host domains will have different Approov tokens associated with
 * them so it is important that the Approov token is only sent to requests for that domain. If the
 * domain has not been configured in the account then an error is obtained. Note that the provided
 * URL may be suffixed by "?measurement" to initiate a measurement process for use with integrity and
 * device proofs.
 *
 * @param url provides the URL for which a token is being fetched
 * @return results of fetching a token
 */
class func fetchTokenAndWait(_ url: String) -> ApproovTokenFetchResult

Asynchronous Token Fetch

Java

/**
 * Interface that must be implemented to receive token fetch callbacks for the
 * fetchApproovToken() method.
 */
public interface TokenFetchCallback {
   /**
    * Callback function to be implemented in the business logic.
    *
    * @param result is the TokenFetchResult
    */
   void approovCallback(TokenFetchResult result);
}

/**
 * Initiates an asynchronous request to obtain an Approov token and other results. The call returns
 * immediately and when the token is fetched (or if the request times out due to an error) then
 * a callback method is called on the supplied interface instance object. This callback is made
 * on a different thread. If an Approov token fetch has been completed previously and the tokens
 * are unexpired then this callback may be very rapid without a need to perform a network transaction.
 * Note though that the caller should never cache the Approov token as it may become invalidated at
 * any point.
 *
 * If a new Approov token is required then a more extensive app measurement is performed that involves
 * communicating with the Approov cloud service.There is a chance that due to poor network
 * connectivity or other factors an Approov token cannot be obtained, and this is reflected in the
 * returned status.
 *
 * All calls must provide a URL which provides the endpoint of the API to which the Approov
 * token is going to be sent. Different host domains will have different Approov tokens associated with
 * them so it is important that the Approov token is only sent to requests for that domain. If the
 * domain has not been configured in the account then an error is obtained. Note that the provided
 * URL may be suffixed by "?measurement" to initiate a measurement process for use with integrity and
 * device proofs.
 *
 * @param callback is an instance that implements TokenFetchCallback whose callback
 * @param url provides the URL for which a token is being fetched
 */
public static final void fetchApproovToken(TokenFetchCallback callback, String url);

Objective-C

typedef void (^ApproovTokenFetchCallback)(ApproovTokenFetchResult *_Nonnull result);

/**
 * Initiates an asynchronous request to obtain an Approov token and other results. The call returns
 * immediately and when the token is fetched (or if the request times out due to an error) then
 * a callback function is called with the result. This callback is made on a different thread. If
 * an Approov token fetch has been completed previously and the token are unexpired then this callback
 * may be very rapid without a need to perform a network transaction. Note though that the caller
 * should never cache the Approov token as it may become invalidated at any point.
 *
 * If a new Approov token is required then a more extensive app measurement is performed that involves
 * communicating with the Approov cloud service. There is a chance that due to poor network
 * connectivity or other factors an Approov token cannot be obtained, and this is reflected in the
 * returned status.
 *
 * All calls must provide a URL which provides the endpoint of the API to which the Approov
 * token is going to be sent. Different host domains will have different Approov tokens associated with
 * them so it is important that the Approov token is only sent to requests for that domain. If the
 * domain has not been configured in the account then an error is obtained. Note that the provided
 * URL may be suffixed by "?measurement" to initiate a measurement process for use with integrity and
 * device proofs.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param url provides the URL for which a token is being fetched
 */
+ (void)fetchApproovToken:(nonnull ApproovTokenFetchCallback)callbackHandler :(nonnull NSString *)url;

Swift

typealias ApproovTokenFetchCallback = (ApproovTokenFetchResult) -> Void

/**
 * Initiates an asynchronous request to obtain an Approov token and other results. The call returns
 * immediately and when the token is fetched (or if the request times out due to an error) then
 * a callback function is called with the result. This callback is made on a different thread. If
 * an Approov token fetch has been completed previously and the token are unexpired then this callback
 * may be very rapid without a need to perform a network transaction. Note though that the caller
 * should never cache the Approov token as it may become invalidated at any point.
 *
 * If a new Approov token is required then a more extensive app measurement is performed that involves
 * communicating with the Approov cloud service. There is a chance that due to poor network
 * connectivity or other factors an Approov token cannot be obtained, and this is reflected in the
 * returned status.
 *
 * All calls must provide a URL which provides the endpoint of the API to which the Approov
 * token is going to be sent. Different host domains will have different Approov tokens associated with
 * them so it is important that the Approov token is only sent to requests for that domain. If the
 * domain has not been configured in the account then an error is obtained. Note that the provided
 * URL may be suffixed by "?measurement" to initiate a measurement process for use with integrity and
 * device proofs.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param url provides the top URL for which a token is being fetched
 */
class func fetchToken(_ callbackHandler: ApproovTokenFetchCallback, _ url: String)

Synchronous Secure String Fetch

Java

/**
 * Initiates a synchronous request to obtain, or update, a string held securely by the SDK. The
 * call only returns when the secure string has been obtained (or if the request times out due to
 * an error, or if the request is rejected). This provides the secure string value. It is also
 * possible to update the secure string value by providing a new definition. In this case the
 * new value is returned as the secure string. Use of an empty string for newDef removes the
 * string entry. Note that after an initial fetch secure strings will be available for some period
 * until they expire, with no latency for a network operation. If the string is not defined then
 * the UNKNOWN_KEY error status is returned. If the attestation process fails then the error
 * status REJECTED is returned. Finally, if the feature is not enabled then the DISABLED status
 * is returned.
 *
 * @param key is the name of the key (max 64 characters) that the secure string is held against
 * @param newDef is any new definition for the secure string, or null otherwise
 * @return results of fetching the secure string
 * @throws IllegalArgumentException if the key is empty or too long
 */
public static final TokenFetchResult fetchSecureStringAndWait(String key, String newDef);

Objective-C

/**
 * Initiates a synchronous request to obtain, or update, a string held securely by the SDK. The
 * call only returns when the secure string has been obtained (or if the request times out due to
 * an error, or if the request is rejected). This provides the secure string value. It is also
 * possible to update the secure string value by providing a new definition. In this case the
 * new value is returned as the secure string. Use of an empty string for newDef removes the
 * string entry. Note that after an initial fetch secure strings will be available for some period
 * until they expire, with no latency for a network operation. If the string is not defined then
 * the UnknownKey error status is returned. If the attestation process fails then the error status
 * Rejected is returned. If the provided key is invalid then a BadKey status is returned. Finally,
 * if the feature is not enabled then the Disabled status is returned.
 *
 * @param key is the name of the key (max 64 characters) that the secure string is held against
 * @param newDef is any new definition for the secure string, or nil otherwise
 * @return results of fetching the secure string
 */
+ (nonnull ApproovTokenFetchResult *)fetchSecureStringAndWait:(nonnull NSString *)key :(nullable NSString *)newDef;

Swift

/**
 * Initiates a synchronous request to obtain, or update, a string held securely by the SDK. The
 * call only returns when the secure string has been obtained (or if the request times out due to
 * an error, or if the request is rejected). This provides the secure string value. It is also
 * possible to update the secure string value by providing a new definition. In this case the
 * new value is returned as the secure string. Use of an empty string for newDef removes the
 * string entry. Note that after an initial fetch secure strings will be available for some period
 * until they expire, with no latency for a network operation. If the string is not defined then
 * the UnknownKey error status is returned. If the attestation process fails then the error status
 * Rejected is returned. If the provided key is invalid then a BadKey status is returned. Finally,
 * if the feature is not enabled then the Disabled status is returned.
 *
 * @param key is the name of the key (max 64 characters) that the secure string is held against
 * @param newDef is any new definition for the secure string, or nil otherwise
 * @return results of fetching the secure string
 */
class func fetchSecureStringAndWait(_ key: String, _ newDef: string) -> ApproovTokenFetchResult

Asynchronous Secure String Fetch

Java

/**
 * Interface that must be implemented to receive token fetch callbacks for the
 * fetchSecureString() method.
 */
public interface TokenFetchCallback {
   /**
    * Callback function to be implemented in the business logic.
    *
    * @param result is the TokenFetchResult
    */
   void approovCallback(TokenFetchResult result);
}

/**
 * Initiates an asynchronous request to obtain, or update, a string held securely by the SDK. The call
 * returns immediately. After the secure string is fetched (or if the request times out due to an
 * error, or if the request is rejected), then a callback method is called on the supplied interface
 * instance object. This callback is made on a different thread. This provides the secure string value.
 * It is also possible to update the secure string value by providing a new definition. In this case the
 * new value is returned as the secure string. Use of an empty string for newDef removes the string entry.
 * Note that after an initial fetch secure strings will be available for some period until they expire, with
 * no latency for a network operation. If the string is not defined then the UNKNOWN_KEY error status is
 * returned. If the attestation process fails then the error status REJECTED is returned. Finally, if the
 * feature is not enabled then the DISABLED status is returned.
 *
 * @param callback is an instance that implements TokenFetchCallback
 * @param key is the name of the key (max 64 characters) that the secure string is held against
 * @param newDef is any new definition for the secure string, or null otherwise
 * @throws IllegalArgumentException if the key is empty or too long
 */
public static final void fetchSecureString(TokenFetchCallback callback, String key, String newDef);

Objective-C

typedef void (^ApproovTokenFetchCallback)(ApproovTokenFetchResult *_Nonnull result);

/**
 * Initiates an asynchronous request to obtain, or update, a string held securely by the SDK. The call
 * returns immediately. After the secure string is fetched (or if the request times out due to an
 * error, or if the request is rejected), then a callback method is called on the supplied interface
 * instance object. This callback is made on a different thread. This provides the secure string value.
 * It is also possible to update the secure string value by providing a new definition. In this case the
 * new value is returned as the secure string. Use of an empty string for newDef removes the string entry.
 * Note that after an initial fetch secure strings will be available for some period until they expire, with
 * no latency for a network operation. If the string is not defined then the UnknownKey error status
 * is returned. If the attestation process fails then the error status Rejected is returned. If the provided
 * key is invalid then a BadKey status is returned. Finally, if the feature is not enabled then the Disabled
 * status is returned.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param key is the name of the key (max 64 characters) that the secure string is held against
 * @param newDef is any new definition for the secure string, or nil otherwise
 */
+ (void)fetchSecureString:(nonnull ApproovTokenFetchCallback)callbackHandler :(nonnull NSString *)key :(nullable NSString *)newDef;

Swift

typealias ApproovTokenFetchCallback = (ApproovTokenFetchResult) -> Void

/**
 * Initiates an asynchronous request to obtain, or update, a string held securely by the SDK. The call
 * returns immediately. After the secure string is fetched (or if the request times out due to an
 * error, or if the request is rejected), then a callback method is called on the supplied interface
 * instance object. This callback is made on a different thread. This provides the secure string value.
 * It is also possible to update the secure string value by providing a new definition. In this case the
 * new value is returned as the secure string. Use of an empty string for newDef removes the string entry.
 * Note that after an initial fetch secure strings will be available for some period until they expire, with
 * no latency for a network operation. If the string is not defined then the UnknownKey error status
 * is returned. If the attestation process fails then the error status Rejected is returned. If the provided
 * key is invalid then a BadKey status is returned. Finally, if the feature is not enabled then the Disabled
 * status is returned.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param key is the name of the key (max 64 characters) that the secure string is held against
 * @param newDef is any new definition for the secure string, or nil otherwise
 */
class func fetchSecureString(_ callbackHandler: ApproovTokenFetchCallback, _ key: String, _ newDef: String)

Synchronous Custom JWT Fetch

Java

/**
 * Initiates a synchronous request to obtain a custom JWT with the given payload. The call only
 * returns when the custom JWT has been obtained (or if the request times out due to an error, or
 * if the request is rejected). The payload must be valid JSON. If the attestation process fails
 * then the error status REJECTED is returned. Finally, if the feature is not enabled then the
 * DISABLED status is returned.
 *
 * @param payload provide marshaled JSON to be included in the custom JWT to be fetched
 * @return results of fetching a token
 * @throws IllegalArgumentException if the payload is not valid JSON
 */
public static final TokenFetchResult fetchCustomJWTAndWait(String payload);

Objective-C

/**
 * Initiates a synchronous request to obtain a custom JWT with the given payload. The call only
 * returns when the custom JWT has been obtained (or if the request times out due to an error, or
 * if the request is rejected). The payload must be valid JSON or else a BadPayload error status
 * is returned. If the attestation process fails then the error status Rejected is returned.
 * Finally, if the feature is not enabled then the Disabled status is returned.
 *
 * @param payload provide marshaled JSON to be included in the custom JWT to be fetched
 * @return results of fetching a token
 */
+ (nonnull ApproovTokenFetchResult *)fetchCustomJWTAndWait:(nonnull NSString *)payload;

Swift

/**
 * Initiates a synchronous request to obtain a custom JWT with the given payload. The call only
 * returns when the custom JWT has been obtained (or if the request times out due to an error, or
 * if the request is rejected). The payload must be valid JSON or else a BadPayload error status
 * is returned. If the attestation process fails then the error status Rejected is returned. Finally,
 * if the feature is not enabled then the Disabled status is returned.
 *
 * @param payload provide marshaled JSON to be included in the custom JWT to be fetched
 * @return results of fetching a token
 */
class func fetchCustomJWTAndWait(_ payload: String) -> ApproovTokenFetchResult

Asynchronous Custom JWT Fetch

Java

/**
 * Interface that must be implemented to receive token fetch callbacks for the
 * fetchCustomJWT() method.
 */
public interface TokenFetchCallback {
   /**
    * Callback function to be implemented in the business logic.
    *
    * @param result is the TokenFetchResult
    */
   void approovCallback(TokenFetchResult result);
}

/**
 * Initiates an asynchronous request to obtain a custom JWT with the given payload. The call returns
 * immediately. After the token is fetched (or if the request times out due to an error, or if the
 * request is rejected) then a callback method is called on the supplied interface instance object.
 * This callback is made on a different thread. The payload must be valid JSON. If the attestation
 * process fails then the error status REJECTED is returned. Finally, if the feature is not enabled
 * then the DISABLED status is returned.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param payload provide marshaled JSON to be included in the custom JWT to be fetched
 * @throws IllegalArgumentException if the payload is not valid JSON
 */
public static final void fetchCustomJWT(TokenFetchCallback callback, String payload);

Objective-C

typedef void (^ApproovTokenFetchCallback)(ApproovTokenFetchResult *_Nonnull result);

/**
 * Initiates an asynchronous request to obtain a custom JWT with the given payload. The call returns
 * immediately. After the token is fetched (or if the request times out due to an error, or if the
 * request is rejected) then a callback method is called on the supplied interface instance object.
 * This callback is made on a different thread. The payload must be valid JSON or else a BadPayload
 * error status is returned. If the attestation process fails then the error status Rejected is
 * returned. Finally, if the feature is not enabled then the Disabled status is returned.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param payload provide marshaled JSON to be included in the custom JWT to be fetched
 */
+ (void)fetchCustomJWT:(nonnull ApproovTokenFetchCallback)callbackHandler :(nonnull NSString *)payload;

Swift

typealias ApproovTokenFetchCallback = (ApproovTokenFetchResult) -> Void

/**
 * Initiates an asynchronous request to obtain a custom JWT with the given payload. The call returns
 * immediately. After the token is fetched (or if the request times out due to an error, or if the
 * request is rejected) then a callback method is called on the supplied interface instance object.
 * This callback is made on a different thread. The payload must be valid JSON or else a BadPayload
 * error status is returned. If the attestation process fails then the error status Rejected is
 * returned. Finally, if the feature is not enabled then the Disabled status is returned.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param payload provide marshaled JSON to be included in the custom JWT to be fetched
 */
class func fetchCustomJWT(_ callbackHandler: ApproovTokenFetchCallback, _ payload: String)