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

# Marketo Integration

> How to set up and configure Gradial with Adobe Marketo Engage — a CRM platform — using OAuth 2.0 Client Credentials authentication.

## Overview

Gradial integrates with Marketo as a CRM platform, enabling content synchronization, personalization token management, and email asset operations at scale. This integration allows you to build and update email templates, manage landing pages, and maintain reusable content items — including Snippets and Tokens — within your Marketo instance, coordinated through Gradial's Email Agent.

## Authentication Method

Marketo uses OAuth 2.0 Client Credentials for API authentication. This server-to-server authentication method is ideal for automated integrations as it doesn't require user interaction after initial setup.

### OAuth 2.0 Client Credentials

**Required for all Marketo integrations.** This authentication method uses a Client ID and Client Secret to obtain access tokens directly from Marketo's identity service. Tokens are automatically refreshed by Gradial as needed.

## Prerequisites

Before starting the integration, ensure you have:

* Admin access to your Marketo instance
* Permission to create API-only users and custom services
* Your Marketo Base URL (typically `https://[instance-id].mktoweb.com`)

## Integration Steps

### Step 1: Create an API-Only User in Marketo

**What this step does:** Creates a dedicated user account that Gradial will use to authenticate with Marketo's REST API.

1. Log in to your Marketo instance
2. Navigate to **Admin** → **Users & Roles**
3. Click the **Roles** tab
4. Click **New Role** and create a role with the following permissions:
   * **Access API** (required)
   * **Read-Write Assets** (for landing pages and emails)
   * **Read-Only Lead Database** (if personalization features are needed)
5. Click the **Users** tab
6. Click **Invite New User**
7. Fill in the user details:
   * **Email:** Use a service account email (e.g., `gradial-api@yourcompany.com`)
   * **First Name:** `Gradial`
   * **Last Name:** `Integration`
8. On the permissions step, check **API Only**
9. Assign the role you created in step 4
10. Click **Send** to create the user

> **Note:** API-Only users do not consume a Marketo user license and cannot log in to the Marketo UI.

### Step 2: Create a Custom Service (LaunchPoint)

**What this step does:** Creates the OAuth client application that generates the Client ID and Client Secret needed for authentication.

1. Navigate to **Admin** → **Integration** → **LaunchPoint**
2. Click **New** → **New Service**
3. Configure the service with the following values:
   * **Display Name:** `Gradial`
   * **Service:** Select **Custom**
   * **Description:** `Gradial CMS Integration`
   * **API Only User:** Select the user created in Step 1
4. Click **Create**

### Step 3: Retrieve OAuth Credentials

**What this step does:** Obtains the Client ID and Client Secret that Gradial needs to authenticate.

1. In the LaunchPoint services list, find the **Gradial** service you just created
2. Click **View Details**
3. Note the following values:
   * **Client ID**
   * **Client Secret**

> **Important:** Keep the Client Secret secure. This credential provides access to your Marketo instance and should be treated as a sensitive security credential. If compromised, you can regenerate the secret from the LaunchPoint service details.

### Step 4: Find Your Marketo Base URL and Identity URL

**What this step does:** Retrieves the endpoint URLs needed for API authentication.

1. Navigate to **Admin** → **Integration** → **Web Services**
2. Under the **REST API** section, note:
   * **Endpoint URL:** This is your Marketo Base URL (e.g., `https://123-ABC-456.mktoweb.com`)
   * **Identity URL:** This is used for token generation (e.g., `https://123-ABC-456.mktorest.com/identity`)

> **Note:** The Identity URL is used as the Token URL Override if your Marketo instance uses a non-standard configuration.

### Step 5: Configure the Integration in Gradial

**What this step does:** Connects Gradial to your Marketo instance using the credentials obtained in previous steps.

<img src="https://mintcdn.com/gradial/lr_J8YANuJGvu8Gz/images/image-1.png?fit=max&auto=format&n=lr_J8YANuJGvu8Gz&q=85&s=df116560ba7ecb9a32263a1696e70f61" alt="Image" width="298" height="292" data-path="images/image-1.png" />

1. In Gradial, navigate to **Settings** → **Integrations**
2. Click on **Marketo** under Add Integration
3. Fill in the integration form:
   * **Integration Name:** A friendly name to identify this connection (e.g., `My Marketo Instance` or `Production Marketo`)
   * **Marketo Base URL:** Enter your Endpoint URL from Step 4 (e.g., `https://123-ABC-456.mktoweb.com`)
   * **Authentication Type:** Select **OAuth 2.0 Client Credentials**
   * **Client ID:** Enter the Client ID from Step 3
   * **Client Secret:** Enter the Client Secret from Step 3
   * **Token URL Override (Optional):** Leave empty unless your Marketo instance uses a custom identity endpoint. If needed, enter your Identity URL from Step 4
4. Click **Save**

## Testing the Integration

After saving the integration, Gradial will automatically attempt to authenticate with your Marketo instance. You can verify the connection status in the Integrations list.

### Expected Behavior

* **Success:** The integration shows a "Connected" status with a green indicator
* **Authentication Error:** Verify your Client ID and Client Secret are correct
* **Connection Error:** Verify your Marketo Base URL is correct and accessible

### Common Issues

| Issue                  | Cause                         | Solution                                                   |
| :--------------------- | :---------------------------- | :--------------------------------------------------------- |
| `unauthorized` error   | Invalid Client ID or Secret   | Verify credentials in Marketo LaunchPoint                  |
| `unknown host` error   | Incorrect Base URL            | Check the Endpoint URL in Marketo Admin → Web Services     |
| `access_denied` error  | API user lacks permissions    | Verify the API-only user has the required role permissions |
| Token refresh failures | Client Secret was regenerated | Update the Client Secret in Gradial                        |

## API Permissions Reference

The following table shows the Marketo API permissions and their use in Gradial:

| Permission              | Required | Purpose                                    |
| :---------------------- | :------- | :----------------------------------------- |
| Access API              | Yes      | Required for all API access                |
| Read-Write Assets       | Yes      | Landing pages, emails, forms, and snippets |
| Read-Only Lead Database | Optional | Personalization tokens and lead data       |
| Read-Write Activities   | Optional | Activity tracking and logging              |

## Need Help?

Contact your Gradial representative for additional support with your Marketo integration.