# 2. Authentication

# Introduction

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:

# 1. Install 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:

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

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

Once the user is redirected to your platform, you can verify the app_id and authenticate the user on your end.

# Example Request

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

# 2. Xcode Decryption

Before anything, you must store the xcode temporary in a key-value database (like Redis) or in memory, or in any other storage solution. You will need the xcode for verification process and for the callback also.

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 Published Apps section, like this:

# Helper Functions

Tip

In the Xcode Decryption Guide page, you will learn how to decrypt xcode using your app secret in several programming languages: Go, JavaScript (Node), Python, PHP, .NET (C#), and Ruby.

Just copy-past and you're done 😊

# Verification

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

REDIRECT (GET)
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.

If the validation is correct, you will receive a POST request in your callback.

# 3. Callback Flow

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.
access_token: A token provided for authenticating and authorizing the user for API calls after installation.

You must respond with a 200 status code with no content; otherwise, the installation will fail on our end.

# Example Request

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

# Access Token

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.

Save the access_token in your database and use it for any future API interactions. This token does not expire unless the user uninstalls the app.