Application Environment Verification Getting Started: Setup and First Call

Getting started overview

To begin using Application Environment Verification, the process involves several key steps designed to protect your mobile application's backend API communication. This includes setting up an account, integrating the Application Environment Verification SDK into your mobile client, and configuring your backend API to validate the tokens generated by the SDK. The goal is to ensure that all API requests originate from legitimate, uncompromised instances of your application.

The Application Environment Verification system operates by embedding a client-side SDK within your mobile application. This SDK generates a short-lived token that is then sent with every API request to your backend. Your backend, in turn, verifies this token with the Application Environment Verification cloud service. If the token is valid, it confirms that the request came from an authentic and untampered application environment, allowing the request to proceed (Approov API reference documentation).

Here's a quick reference table outlining the initial steps:

Create an account and get keys

Before integrating Application Environment Verification into your application, you need to create an account and obtain the necessary credentials. Application Environment Verification offers a 14-day free trial, which is suitable for initial setup and testing (Approov pricing page).

1. Sign Up: Navigate to the Approov homepage and locate the sign-up or free trial option. Follow the prompts to create your account. This typically involves providing an email address and setting a password.
2. Access Dashboard: Once your account is created, you will gain access to the Application Environment Verification administrative dashboard. This dashboard is your central hub for managing applications, viewing metrics, and retrieving configuration details.
3. Obtain API Key/Secret: Within the dashboard, you will need to retrieve your Application Environment Verification API key or tenant secret. This credential is vital for both your mobile SDK integration and your backend service configuration. The exact location for finding this key may vary slightly within the dashboard but is generally found under 'Settings' or 'API Keys'. Keep this key secure, as it grants access to your Application Environment Verification services.

Your Application Environment Verification account provides a secure way to manage your mobile applications and their associated API protection policies. The API key acts as a unique identifier for your tenant and is critical for both the client-side SDK initialization and the server-side token verification process.

Your first request

Performing your first verified request involves two main components: client-side integration within your mobile application and server-side validation on your backend API. This section outlines the general steps, while specific code examples will depend on your chosen SDK and backend language (Approov documentation portal).

Client-Side Integration (Mobile App)

The Application Environment Verification SDK needs to be initialized within your mobile application. The process typically involves:

1. Add SDK Dependency: Integrate the Application Environment Verification SDK into your project using your platform's package manager (e.g., CocoaPods for iOS, Gradle for Android, npm for React Native (Android setup guide)).
2. Initialize SDK: Call the SDK's initialization method early in your application's lifecycle, providing your Application Environment Verification API key. This sets up the SDK's internal mechanisms for generating tokens.
3. Fetch Approov Token: Before making an API request that you wish to protect, your app will need to fetch an Application Environment Verification token. This is typically an asynchronous call to the SDK that returns a short-lived, cryptographically signed token.
4. Attach Token to API Request: Include the fetched Application Environment Verification token in the HTTP headers of your API request. The standard header for this is usually Approov-Token.

Example (Conceptual Swift for iOS):

import ApproovSDK

// ... in your AppDelegate or initial view controller
ApproovSDK.initialize("YOUR_APPROOV_API_KEY", 
                      config: nil, 
                      successHandler: { 
                          print("Approov SDK initialized successfully") 
                      }, 
                      errorHandler: { error in 
                          print("Approov SDK initialization failed: \(error)") 
                      })

// ... before making an API call
ApproovSDK.fetchApproovToken("YOUR_API_DOMAIN") { token, error in
    if let approovToken = token {
        var request = URLRequest(url: URL(string: "https://api.example.com/data")!)
        request.addValue(approovToken, forHTTPHeaderField: "Approov-Token")
        // Now perform the URLSession task with this request
    } else if let fetchError = error {
        print("Failed to fetch Approov token: \(fetchError)")
    }
}

Server-Side Integration (Backend API)

Your backend API needs to validate the Application Environment Verification token received from the mobile app. This process typically involves:

1. Receive Token: Extract the Approov-Token header from incoming API requests.
2. Validate Token: Send this token to the Application Environment Verification cloud service for validation. Application Environment Verification provides server-side libraries or simple HTTP APIs for this purpose.
3. Conditional Access: Based on the validation response, either allow the API request to proceed (if the token is valid) or reject it (if the token is invalid or missing), indicating that the request did not originate from a legitimate app environment.

Example (Conceptual Node.js with Express):

const express = require('express');
const app = express();
const axios = require('axios'); // For making HTTP requests

app.use(async (req, res, next) => {
  const approovToken = req.headers['approov-token'];
  if (!approovToken) {
    return res.status(401).send('Approov token missing');
  }

  try {
    // This would typically be a call to an Approov SDK or a direct API endpoint
    // For demonstration, assume a validation service at /api/v1/validate-approov-token
    const validationResponse = await axios.post('https://api.approov.io/api/v1/validate-approov-token', {
      token: approovToken
    }, {
      headers: {
        'Authorization': `Bearer YOUR_APPROOV_SECRET_KEY` // Use your backend secret here
      }
    });

    if (validationResponse.data.valid) {
      next(); // Token valid, proceed to the next middleware or route handler
    } else {
      res.status(403).send('Invalid Approov token');
    }
  } catch (error) {
    console.error('Approov token validation error:', error.message);
    res.status(500).send('Approov validation service error');
  }
});

// Your protected API routes
app.get('/protected-data', (req, res) => {
  res.send('This data is protected by Approov!');
});

app.listen(3000, () => console.log('Server running on port 3000'));

Common next steps

Once you have a basic working integration, consider these common next steps to enhance your Application Environment Verification setup:

• Error Handling: Implement robust error handling on both the client and server sides for scenarios where token fetching or validation fails. This ensures your application behaves gracefully under various conditions.
• Policy Configuration: Explore the Application Environment Verification dashboard to configure policies for your protected applications. You can define rules for device integrity checks, jailbreak/root detection, debugger detection, and more (Approov mobile application security policies).
• Advanced Integrations: Consider integrating Application Environment Verification with your existing API Gateway (e.g., Kong Gateway (Kong Gateway documentation), AWS API Gateway, Azure API Management) or CDN for more centralized token validation and performance optimization.
• Testing and Monitoring: Thoroughly test your integration with both legitimate and compromised mobile app environments to ensure the protection works as expected. Utilize the Application Environment Verification dashboard for analytics and monitoring of API requests and threat insights.
• Release Management: Plan your release strategy, considering how Application Environment Verification updates and policy changes will be deployed to your production environment.
• Security Best Practices: Review general API security best practices in conjunction with Application Environment Verification, such as using HTTPS, strong authentication, and authorization mechanisms.

Troubleshooting the first call

Encountering issues during the initial setup is common. Here are some troubleshooting tips for your first Application Environment Verification-protected API call:

• Invalid API Key/Secret: Double-check that the API key used in your mobile SDK initialization and the secret used in your backend validation are correct and match what's in your Application Environment Verification dashboard. Typos are a frequent cause of initialization failures.
• Missing Approov Token Header: Ensure that your mobile application is correctly adding the Approov-Token header to all protected API requests. Use network debugging tools (e.g., Charles Proxy, Fiddler) to inspect outgoing requests from your mobile app.
• Backend Validation Logic: Verify that your backend code correctly extracts the Approov-Token header and initiates the validation call to the Application Environment Verification service. Check for any errors in your backend's API request to the Application Environment Verification validation endpoint.
• Network Connectivity: Confirm that both your mobile device and your backend server have stable network connectivity to reach the Application Environment Verification cloud services. Firewall rules on your backend might block outgoing requests to Application Environment Verification's validation endpoint.
• SDK Initialization Errors: Review the console or log output of your mobile application for any errors reported by the Application Environment Verification SDK during its initialization phase.
• Clock Skew: Ensure that the system clocks on both your mobile device and your backend server are synchronized. Significant clock skew can sometimes lead to token validation issues due to time-sensitive cryptographic checks.
• Approov Dashboard Logs: Check the Application Environment Verification dashboard for logs related to your application and API calls. These logs can provide insights into why tokens might be failing validation.
• SDK Version Compatibility: Ensure you are using a compatible version of the Application Environment Verification SDK with your mobile platform and any other libraries in your project. Refer to the Approov documentation for specific versioning requirements.