# 2. Authentication

Once your app is published in the app marketplace — whether in the development or in_review or production phase — you can test the app installation using your developer accounts (accessible in Integrator Studio).

You'll need the Install URL and Callback URL that you specified during app creation in the studio dashboard.

Here’s the complete flow:

Once the end user selects your app from the app market for installation, they will be redirected to your Install URL with the following query parameters:

{YOUR_INSTALL_URL}?app_id={...}&xcode={...}

• app_id: The ID of your application.
• xcode: An encrypted code used for verifying your app.

https://api.darhamad.com/install?app_id=66f3f4cd7ef4e922a598f147&xcode=0746553f08bacc225a63ff78fdf2d087:32cf601b187101a9ff7db3a475e8e647a427bd3fc08188c48f51648b584197cf7562a4cfb6ade1c326d2c8c0cfd62375

You will need your app's secret to decode the xcode using AES-256-CBC decryption and retrieve the result.
You can find your app secret in the Integrator Studio under the Apps section.
Choose "App Credentials" from the Actions dropdown, like this:

After successful decrypt the xcode, You will redirect the user to this API endpoint for verification:

https://api.armadadelivery.com/integrations/apps/install/verify?xcode={...}&code={...}

• xcode: The xcode that we sent to you.
• code: The encrypted version of xcode that you decrypt using your app secret.

Once the xcode and code are validated, as seen in the previous section, our system will send a POST request to your callback URL with the following JSON data:

• xcode: To identify the process (as seen in the previous section).
• app_data: Contains specific data related to the app:
  • _id: Your app ID.
  • form: The form data that the user submitted during installation (this can be empty or populated based on the app's setup).
• user_data: Contains information about the user who installed the app:
  • reference: A reference ID for the user of Armada.
  • email: The email address of the user.
  • country: The county of the user.
• access_token: A token provided for authenticating and authorizing the user for API calls after installation.

{
  "xcode": "0746553f08bacc225a63ff78fdf2d087:32cf601b187101a9ff7db3a475e8e647a427bd3fc08188c48f51648b584197cf7562a4cfb6ade1c326d2c8c0cfd62375",
  "app_data": {
    "_id": "66e1cfddda272f51185b193c",
    "form": {}
  },
  "user_data": {
    "reference": "66fad2cb76298b39f0ecf859",
    "email": "zakaria@armadadelivery.com",
    "country": "Kuwait",
  },
  "access_token": "arap_363200ea05878276d75cbfa1c07c373"
}

Example of pre-required inputs during installation:

These inputs are typically form fields defined by the integrator in advance. When a user installs an app, they are required to fill them out.

{
  "xcode": "0746553f08bacc225a63ff78fdf2d087:32cf601b187101a9ff7db3a475e8e647a427bd3fc08188c48f51648b584197cf7562a4cfb6ade1c326d2c8c0cfd62375",
  "app_data": {
    "_id": "66e1cfddda272f51185b193c",
      "form": {
        "inputs": [
          { "name": "Level", "value": 5 }
          { "name": "Store ID", "value": "T4857HR1B" }
          { "name": "Enable email notification?", "value": false }
        ]
      }
  },
  "user_data": {
    "reference": "66fad2cb76298b39f0ecf859",
    "email": "zakaria@armadadelivery.com",
    "country": "Kuwait",
  },
  "access_token": "arap_363200ea05878276d75cbfa1c07c373"
}

The access_token is associated with the specific user who installed your app, so any action taken with this token will affect that user’s instance of the app.

The uninstall flow is not part of the authentication process. Instead, it exists to ensure a smooth and consistent user experience on both sides — your app and the Armada platform.

When a user clicks the "Uninstall" button from the app marketplace, the integration between your app and that user will be removed. At that moment, Armada sends a POST request to your app’s registered Uninstall URL with the following payload:

• app_data: Contains specific data related to the app:
  • _id: Your app ID.
• user_data: Contains information about the user who uninstalled the app:
  • reference: A reference ID for the user of Armada.
  • email: The email address of the user.
  • country: The county of the user.

POST Request to Your App's Uninstall URL:

{
  "app_data": {
    "_id": "66e1cfddda272f51185b193c",
  },
  "user_data": {
    "reference": "66fad2cb76298b39f0ecf859",
    "email": "zakaria@armadadelivery.com",
    "country": "Kuwait",
  },
}