---
title: "Introduction"
slug: "introduction-connect"
updated: 2026-07-31T07:30:14Z
published: 2026-07-31T07:30:14Z
canonical: "docs.mapp.com/introduction-connect"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

Mapp Connect is a data layer for Mapp Engage. It uses add-ons and asynchronous API connections to allow you to exchange data between third-party marketing applications and Mapp Engage.

Use of Mapp Connect

- Access all your third-party integrations from one central location
- Import contact and eCommerce data from your own or third-party applications into Mapp Engage
- Unify source data into the required format during the import
- Send Emails, SMS, and Push Messages using the imported data
- Create Whiteboard automations triggered by external events

Here, you will find a description of the [API Endpoints](/v1-api/apidocs/api-endpoints).

## Authentication

Mapp Connect calls authenticate using a JSON Web-Based Token (JWT) created from your integration number and secret key. You can find this information in the Mapp Connect UI and re-generate the secret there. To generate the JWT, you can follow one of these code samples:

PostmanJavaPHP

```json
var Property = require('postman-collection').Property;
function encodeParams(object) {
    let buff = Buffer.from(JSON.stringify(object));
    let base64data = normalizeBase64string(buff.toString('base64')); return base64data;
}
function normalizeBase64string(base64string) {
    return base64string.replace('+', '-').replace('/', '_').replace(/=+$/, '');
}
let request_body = pm.request.body.raw;
let request_uri = [...pm.request.url.path];
request_uri.shift();
request_uri = '/' + request_uri.join('/')
request_uri = Property.replaceSubstitutions(request_uri, pm.collectionVariables.toObject());
let query_string = pm.request.url.getQueryString();
let key = "............."; // add the secret key of the integration here - can be (re-)generated in Mapp Connect UI
let request_data = request_uri.toString();
 if (request_body) {
    request_data += '|' + request_body;
}
if (query_string) {
    request_data += '|' + query_string.toString();
}
console.log(request_data);
let request_hash = CryptoJS.SHA1(request_data).toString(CryptoJS.digest);
const jwtHeader = {
    alg: 'HS256'
};
const jwtBody = {
    'request-hash': request_hash,
    exp: Date.now() + 600000
};
const encodedBody = encodeParams(jwtBody);
const encodedHeader = encodeParams(jwtHeader);
const signature = CryptoJS.HmacSHA256(encodedHeader + '.' + encodedBody, key).toString(CryptoJS.enc.Base64)
let jwt = `${encodedHeader}.${encodedBody}.${signature}`;
console.log(jwt);
pm.request.headers.add({key: "auth-token", value: jwt});
```

```java
/*
 * MappConnectHmacAuth
 *
 * This is a sample Java client demonstrating authentication with Mapp Connect using HMAC JWT.
 *
 * Usage Instructions:
 * 1. Set your integration ID and secret in the constants below.
 * 2. Use the verbose flag to enable detailed debug output if needed.
 * 3. Run the program to send a GET request to the /ping endpoint and print the response.
 *
 * This sample demonstrates:
 *  - How to construct the request hash and JWT for Mapp Connect authentication.
 *  - How to send authenticated HTTP requests using Java.
 *  - How to control output verbosity for easier debugging and integration testing.
 */

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;
import java.io.BufferedReader;
import java.io.InputStreamReader;

public class MappConnectHmacAuth {

    // Cluster URL for Mapp Connect API
    private static final String CLUSTER_URL = "https://jamie.g.shortest-route.com";
    // Your integration ID
    private static final String INTEGRATION_ID = "xxx";
    // Your integration secret
    private static final String SECRET = "xxx";
    // Token expiry in milliseconds (10 minutes)
    private static final long TOKEN_EXPIRY_MS = 600_000L;

    public static void main(String[] args) throws Exception {
        // Example usage for GET request
        String getResponse = callApiWithHmacAuth(
            "GET", // HTTP method
            "/api/v1/integration/" + INTEGRATION_ID + "/ping", // endpoint
            "", // body (empty for GET)
            "", // query string (empty for GET)
            false // verbose output
        );
        System.out.println("GET response: " + getResponse);

        // Example usage for POST request
        // For simple JSON bodies, string concatenation is sufficient.
        // For more complex or production use cases, it is recommended to utilize a JSON library such as Gson or Jackson for safer and more maintainable code.
        // String newEmail = "user@example.com";
        // String postBody = "{" +
        //     "\"email\":\"" + newEmail + "\"," +
        //     "\"group\":0," +
        //     "\"firstname\":\"testName\"}";
        // 
        // String postResponse = callApiWithHmacAuth(
        //     "POST",
        //     "/api/v1/integration/" + INTEGRATION_ID + "/event",
        //     postBody,
        //     "subtype=user",
        //     true // verbose output
        // );
        // System.out.println("POST response: " + postResponse);
    }

    /**
     * Calls Mapp Connect API with HMAC JWT authentication.
     * Supports GET and POST requests.
     *
     * @param method "GET" or "POST"
     * @param endpoint API endpoint (e.g. "/api/v1/integration/.../ping")
     * @param body Request body for POST, empty for GET
     * @param query Query string, e.g. "param=value", or empty
     * @param verbose true for debug output, false for only response
     * @return API response as String
     * @throws Exception on network or crypto errors
     */
    public static String callApiWithHmacAuth(String method, String endpoint, String body, String query, boolean verbose) throws Exception {
        // Null checks for parameters
        if (method == null) throw new IllegalArgumentException("HTTP method cannot be null");
        if (endpoint == null) throw new IllegalArgumentException("Endpoint cannot be null");

        // Build full request path for Mapp Connect
        String fullRequestPath = "/charon" + endpoint;

        // Build request-data string for hashing
        StringBuilder requestData = new StringBuilder(endpoint);
        if (body != null && !body.isEmpty()) requestData.append("|").append(body);
        if (query != null && !query.isEmpty()) requestData.append("|").append(query);

        // Compute SHA1 hash of request-data
        String requestHash = sha1Hex(requestData.toString());

        // Build JWT header and payload
        String jwtHeader = "{\"alg\":\"HS256\"}";
        long exp = System.currentTimeMillis() + TOKEN_EXPIRY_MS; // Use constant for expiry
        String jwtPayload = "{\"request-hash\":\"" + requestHash + "\",\"exp\":" + exp + "}";

        // Encode header and payload in base64url
        String encodedHeader = normalizeBase64(Base64.getEncoder().encodeToString(jwtHeader.getBytes(StandardCharsets.UTF_8)));
        String encodedBody = normalizeBase64(Base64.getEncoder().encodeToString(jwtPayload.getBytes(StandardCharsets.UTF_8)));
        String unsignedToken = encodedHeader + "." + encodedBody;

        // Sign the token with your secret
        String signature = normalizeBase64(hmacSha256(unsignedToken, SECRET));
        String jwt = unsignedToken + "." + signature;

        // Print request info if verbose
        if (verbose) {
            System.out.println("========= Outgoing Request =========");
            System.out.println("URL: " + CLUSTER_URL + fullRequestPath + (query.isEmpty() ? "" : ("?" + query)));
            System.out.println("Method: " + method);
            System.out.println("Headers:");
            System.out.println("  Content-Type: application/json");
            System.out.println("  auth-token: " + jwt);
            System.out.println("Body:");
            System.out.println(body.isEmpty() ? "  [No body for GET request]" : "  " + body);
            System.out.println("=== Debugging Hash Input ===");
            System.out.println("request-data: " + requestData);
            System.out.println("request-hash: " + requestHash);
            System.out.println("====================================\n");
        }

        // Build URI (add query string if present)
        URI uri = new URI(CLUSTER_URL + fullRequestPath + (query.isEmpty() ? "" : ("?" + query)));
        URL url = uri.toURL();
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setConnectTimeout(10_000); // 10 seconds connect timeout
        conn.setReadTimeout(10_000);    // 10 seconds read timeout
        conn.setRequestMethod(method);
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setRequestProperty("auth-token", jwt);

        // For POST, send body
        if (method.equals("POST")) {
            conn.setDoOutput(true);
            conn.getOutputStream().write(body.getBytes(StandardCharsets.UTF_8));
        }
        int responseCode = conn.getResponseCode();
        // Use try-with-resources for BufferedReader
        try (BufferedReader reader = new BufferedReader(new InputStreamReader(
                (responseCode >= 200 && responseCode < 300) ? conn.getInputStream() : conn.getErrorStream()))) {
            StringBuilder response = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) response.append(line);
            // Print response based on verbosity
            if (verbose) {
                System.out.println("Response Code: " + responseCode);
                System.out.println("Response Body: " + response);
            }
            return response.toString();
        }
    }

    // Helper: SHA1 hex digest
    private static String sha1Hex(String input) throws Exception {
        MessageDigest md = MessageDigest.getInstance("SHA-1");
        byte[] digest = md.digest(input.getBytes(StandardCharsets.UTF_8));
        StringBuilder sb = new StringBuilder();
        for (byte b : digest) sb.append(String.format("%02x", b));
        return sb.toString();
    }

    // Helper: HMAC SHA256 signature, base64 encoded
    private static String hmacSha256(String data, String secret) throws Exception {
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec keySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        sha256_HMAC.init(keySpec);
        byte[] rawHmac = sha256_HMAC.doFinal(data.getBytes(StandardCharsets.UTF_8));
        return Base64.getEncoder().encodeToString(rawHmac);
    }

    // Helper: Convert base64 to base64url (RFC 4648)
    private static String normalizeBase64(String b64) {
        return b64.replace('+', '-').replace('/', '_').replaceAll("=+$", "");
    }
}
```

```php
<?php
/*
 * MappConnectHmacAuth
 *
 * This is a sample PHP client demonstrating authentication with Mapp Connect using HMAC JWT.
 *
 * Usage Instructions:
 * 1. Set your integration ID and secret in the constants below.
 * 2. Use the $verbose flag to enable detailed debug output if needed.
 * 3. Run the script to send a GET request to the /ping endpoint and print the response.
 *
 * This sample demonstrates:
 *  - How to construct the request hash and JWT for Mapp Connect authentication.
 *  - How to send authenticated HTTP requests using PHP and cURL.
 *  - How to control output verbosity for easier debugging and integration testing.
 */

// Define your integration ID and secret here
$INTEGRATION_ID = "xxx";
$SECRET = "xxx";
$CLUSTER_URL = "https://jamie.g.shortest-route.com";

function base64UrlEncode($data) {
    return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}

function hmacSha256($data, $secret) {
    return base64UrlEncode(hash_hmac('sha256', $data, $secret, true));
}

function sha1Hex($data) {
    return strtolower(sha1($data));
}

function buildJwt($requestHash, $secret) {
    $header = ['alg' => 'HS256'];
    $exp = time() * 1000 + 600000; // 10 minutes into the future
    $payload = [
        'request-hash' => $requestHash,
        'exp' => $exp
    ];
    $encodedHeader = base64UrlEncode(json_encode($header));
    $encodedPayload = base64UrlEncode(json_encode($payload));
    $unsignedToken = $encodedHeader . '.' . $encodedPayload;
    $signature = hmacSha256($unsignedToken, $secret);
    return $unsignedToken . '.' . $signature;
}

/**
 * Calls Mapp Connect API with HMAC JWT authentication.
 * Supports GET and POST requests.
 *
 * @param string $method "GET" or "POST"
 * @param string $endpoint API endpoint (e.g. "/api/v1/integration/.../ping")
 * @param string $body Request body for POST, empty for GET
 * @param string $query Query string, e.g. "param=value", or empty
 * @param bool $verbose true for debug output, false for only response
 * @return void
 */
function callApiWithHmacAuth($method, $endpoint, $body = '', $query = '', $verbose = false) {
    global $CLUSTER_URL, $SECRET;
    $fullRequestPath = "/charon" . $endpoint;
    $requestData = $endpoint;
    if (!empty($body)) $requestData .= "|" . $body;
    if (!empty($query)) $requestData .= "|" . $query;
    $requestHash = sha1Hex($requestData);
    $jwt = buildJwt($requestHash, $SECRET);
    $url = $CLUSTER_URL . $fullRequestPath . (empty($query) ? '' : ('?' . $query));
    if ($verbose) {
        echo "========= Outgoing Request =========\n";
        echo "URL: $url\n";
        echo "Method: $method\n";
        echo "Headers:\n";
        echo "  Content-Type: application/json\n";
        echo "  auth-token: $jwt\n";
        echo "Body:\n";
        echo empty($body) ? "  [No body for GET request]\n" : "  $body\n";
        echo "=== Debugging Hash Input ===\n";
        echo "request-data: $requestData\n";
        echo "request-hash: $requestHash\n";
        echo "====================================\n";
    }
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'auth-token: ' . $jwt
    ]);
    if ($method === 'POST' && !empty($body)) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    }
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($verbose) {
        echo "Response Code: $httpCode\n";
        echo "Response Body: $response\n";
    } else {
        echo $response . "\n";
    }
}

// Example usage for GET request
callApiWithHmacAuth(
    "GET",
    "/api/v1/integration/$INTEGRATION_ID/ping",
    "",
    "",
    false // verbose output
);

// Example usage for POST request
// $newEmail = "user@example.com";
// $postBody = json_encode([
//     "email" => $newEmail,
//     "group" => 0,
//     "firstname" => "testName"
// ]);
// callApiWithHmacAuth(
//     "POST",
//     "/api/v1/integration/$INTEGRATION_ID/event",
//     $postBody,
//     "subtype=user",
//     true // verbose output
// );
?>
```

You can find more information about Mapp Connect in our [Mapp Connect documentation](https://docs.mapp.com/docs/mapp-connect).