Skip to content

AWS Marketplace Connector Setup

This guide walks you through securely connecting your AWS account to Vell using an IAM role deployed via CloudFormation.

Security First

This setup uses AWS best practices: cross-account IAM roles with External ID validation. No credentials or access keys required.

Overview

Time Required: 5-10 minutes Technical Level: Basic AWS CloudFormation knowledge Prerequisites: CloudFormation access (or IAM administrator access)

Wizard versions

Vell ships two versions of the connection wizard. Both deploy the same IAM role with the same permissions — the difference is only the UX you see while you do it. The AWS-side instructions in this guide work for either.

The default /dashboard/user/cloud-connectors/connect URL renders a four-step wizard: Account → Method → Deploy → Verify. Each step is a dedicated page; you click Next to advance. The wizard restores in-progress sessions automatically if you close the tab and come back later.

Append ?v=3 to the wizard URL — /dashboard/user/cloud-connectors/connect?v=3 — for the single-scroll redesign. Three sections (Account → Deploy → Verify) live on one page anchored by a sticky left rail (desktop) or top progress bar (mobile). The flow is driven by an Alpine state machine that picks one of four states server-side: fresh, deploying, awaiting-arn, verified.

What's new in v3:

  • Live AWS Deployment Monitor. The Deploy section centerpiece. Once you start the CloudFormation stack, Vell polls AWS in the background and surfaces the role ARN in the page the moment the stack reaches CREATE_COMPLETE — you don't have to copy/paste anything. The same auto-ARN webhook ran in the background on the default wizard; v3 makes it visible.
  • External ID rendered up front. The Account section displays your External ID immediately on page load instead of waiting until Step 2/3.
  • Express path. A "Skip to verify →" link in the header jumps straight to the Verify section if you already have a deployed IAM role and an ARN ready to paste.
  • Status chip in the header. A live pill shows where you are (Fresh / Deploying / Awaiting ARN / Verified) and survives reloads.
  • OIDC Federation tile. Visible but locked with an "Enterprise" badge — placeholder for an upcoming federation method.
  • Method tiles. IAM Role (default) / OIDC Federation (locked) / Temporary Delegation are presented as choosable tiles in the Account section.

v3 is opt-in for now. The default URL still routes to the 4-step wizard so the v3 variant can A/B in dev before being promoted to default.

What You'll Deploy

The CloudFormation template creates a secure IAM role that allows Vell to:

  • ✅ Access AWS Marketplace API operations only
  • ✅ Read marketplace listing data
  • ✅ Track performance metrics
  • ❌ Cannot access your EC2 instances, databases, or other AWS resources

Security Features

Feature Description
Least Privilege Only grants AWS Marketplace API permissions
External ID Prevents confused deputy attacks
Cross-Account Uses secure cross-account role assumption
Auditable Full CloudFormation template transparency
Revocable Delete the stack anytime to revoke access

Deployment Options

Choose the method that works best for your organization:

Best for: Users with CloudFormation/IAM access

Follow the Self-Service Deployment steps below.

Best for: Users who need to delegate to IAM administrators

Use the Email IAM Administrator feature in the Vell wizard to send deployment instructions to your security team. See Enterprise Delegation.

Self-Service Deployment

These steps work identically in both wizard versions — the wizard hands you the same template and the same External ID either way.

Step 1: Download CloudFormation Template

In the Vell connection wizard, find the Deploy section (4-step: Step 3; v3 single-scroll: Section 2) and click Download Template (.yaml) to save the CloudFormation template to your computer.

Step 2: Open AWS CloudFormation Console

Navigate to the AWS CloudFormation console in the us-east-1 region:

Open CloudFormation Console

Region Requirement

The IAM role must be created in us-east-1 to work with AWS Marketplace APIs.

Step 3: Create Stack

  1. Click Create stack → With new resources (standard)
  2. Select Upload a template file
  3. Click Choose file and select the downloaded .yaml file
  4. Click Next

Step 4: Configure Stack Parameters

Enter the following values exactly as shown in your Vell wizard:

Parameter Value Example
Stack name vell-marketplace-role vell-marketplace-role
ExternalId Your unique External ID from Vell vell-nvukZBq45rwZEvjoL6nKsaBQqmUN1zEV
VellAccountId 253265132499 253265132499

Copy External ID

Use the Copy button in the Vell wizard to ensure accuracy. The External ID is case-sensitive.

Click Next

Step 5: Configure Stack Options

On the "Configure stack options" page:

  • Tags (optional): Add tags if required by your organization
  • Permissions (optional): Leave as default unless your org requires a specific IAM role
  • Stack failure options: Leave as default
  • Advanced options: Leave as default

Click Next

Step 6: Review and Create

  1. Scroll to the bottom of the review page
  2. ✅ Check the box: "I acknowledge that AWS CloudFormation might create IAM resources"
  3. Click Create stack

Step 7: Wait for Completion

The stack deployment takes approximately 2-3 minutes.

Watch the Events tab for progress. Wait until:

  • Stack status: CREATE_COMPLETE ✅

Deployment Progress

You can safely close this window and return later. The deployment continues in the background.

Step 8: Get Role ARN

Once deployment completes:

  1. Click the Outputs tab
  2. Find the key RoleArn
  3. Copy the value (starts with arn:aws:iam::)

Example Output: 

RoleArn: arn:aws:iam::123456789012:role/vell-marketplace-role

v3 wizard auto-detects the ARN

If you started the wizard with ?v=3, you can usually skip the copy/paste — the Live AWS Deployment Monitor in the Deploy section detects the ARN via webhook the moment the stack reaches CREATE_COMPLETE and prefills it in the Verify section. The state chip flips to "Awaiting ARN" → "Verified" without you returning to the page.

Step 9: Return to Vell Wizard

  1. Return to the Vell connection wizard
  2. Click I have deployed the role (default wizard) or scroll to the Verify access section (v3)
  3. Paste the Role ARN — or confirm the auto-detected one
  4. Click Validate Role / Verify
  5. Complete the connection!

Enterprise Delegation

For large organizations where marketplace teams don't have IAM permissions.

How It Works

  1. You: Start the connection wizard in Vell
  2. You: Click "Email Instructions" in Step 3
  3. IAM Admin: Receives professional email with:
    • Step-by-step deployment guide
    • CloudFormation template (attached)
    • Pre-filled External ID and configuration
    • Security notes
  4. IAM Admin: Deploys the stack (5-10 minutes)
  5. IAM Admin: Sends you the Role ARN
  6. You: Enter Role ARN and complete validation

What the Email Contains

The email your IAM administrator receives includes:

  • 📋 Complete deployment instructions (same as this guide)
  • 📎 CloudFormation template as YAML attachment
  • 🔐 Your unique External ID (pre-filled)
  • ⏱️ Time estimate (5-10 minutes)
  • 🔒 Security validation details
  • ❓ Troubleshooting tips

Sending the Email

In the Vell wizard's Deploy section (Step 3 in the default wizard, or Section 2 in v3):

  1. Look for the blue "Need IAM access?" callout
  2. Click Email Instructions
  3. Enter your IAM administrator's email
  4. Add an optional personal message for context
  5. Click Send Email

Your wizard state is saved — you can return once the IAM admin completes deployment. With v3, the Live AWS Deployment Monitor will pick up the deployed role automatically once the IAM admin runs the template, so you'll see the state chip update to "Awaiting ARN" or "Verified" without manual coordination.

IAM Role Permissions

View IAM Policy (click to expand) The CloudFormation template creates an IAM role with these permissions: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MarketplaceReadAccess",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:DescribeEntity",
        "aws-marketplace:ListEntities",
        "aws-marketplace:DescribeChangeSet",
        "aws-marketplace:ListChangeSets",
        "aws-marketplace:GetAgreementTerms",
        "aws-marketplace:SearchAgreements"
      ],
      "Resource": "*"
    }
  ]
}
**What this allows:** - ✅ Read marketplace listing information - ✅ View marketplace agreements and subscriptions - ✅ Track performance metrics **What this does NOT allow:** - ❌ Create or modify marketplace listings - ❌ Access EC2, RDS, S3, or other AWS resources - ❌ Change IAM permissions - ❌ Incur any AWS charges

AgentCore Bedrock Permissions

Using AI Agents?

If you're using AgentCore features (AI Agents, Co-Sell Matching, GTM Planning), additional setup may be required depending on your deployment model.

What is AgentCore?

AgentCore powers AI-driven workflows including: - AI Agents - Multi-step content generation with Brand Voice - Co-Sell Partner Matching - AI-powered partner discovery - Joint GTM Planning - Automated campaign planning - Partner Intelligence - LinkedIn relationship mapping

These features use AWS Bedrock to invoke Claude and Amazon Nova models.

Which Setup Do You Need?

Choose based on your deployment model:

For Platform Operators (SaaS Model)

If you're running the Vell platform using your own AWS account to serve multiple customers:

Platform Operator Setup Guide →

✅ Use when: - You operate Vell as multi-tenant SaaS - Customers share your infrastructure - You pay for Bedrock, charge via credits/subscriptions - Using IAM user vell-ai-bedrock-20251103 or similar

Setup: - Add Bedrock permissions to your IAM user/role - NO External ID needed (same account) - NO CloudFormation for customers - Simple policy attachment

For Enterprise Customers (BYOC Model)

If you're an enterprise customer wanting to use your own AWS account:

BYOC Setup Guide →

✅ Use when: - Enterprise wants to use their own AWS account - Customer wants direct AWS billing - Compliance requires account isolation - Customer controls Bedrock quotas

Setup: - Deploy CloudFormation in customer's account - External ID required (cross-account security) - Customer configures role ARN in Vell dashboard

Quick Diagnosis

Is agent success rate 0.0%?

  1. Go to Dashboard → Agents
  2. Check success rate

If 0.0%: - Platform operators: Your IAM user needs Bedrock permissions → Platform Guide - Enterprise customers: Deploy BYOC CloudFormation → BYOC Guide

Security & Compliance

External ID

The External ID is a unique security token that prevents the "confused deputy" problem.

  • 🔒 Randomly generated for your account
  • 🔐 Required for role assumption
  • 🚫 Never shared or reused
  • ♻️ Rotatable on demand

Trust Relationship

The role trusts only:

  • Principal: Vell's AWS account (253265132499)
  • Condition: Must provide your External ID
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::253265132499:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "your-unique-external-id"
        }
      }
    }
  ]
}

Compliance

  • ✅ SOC 2 Type II compliant
  • ✅ GDPR compliant
  • ✅ Follows AWS Well-Architected Framework
  • ✅ Meets Control Tower requirements

Troubleshooting

Stack Creation Failed

Error: "Resource already exists"

Solution: Delete the existing stack and try again: 

aws cloudformation delete-stack --stack-name vell-marketplace-role --region us-east-1

Role Validation Failed

Common causes:

  1. Incorrect Role ARN
  2. Make sure you copied the full ARN from CloudFormation Outputs

  3. ARN should start with arn:aws:iam::

  4. Wrong External ID

  5. Use the exact External ID from your Vell wizard

  6. External IDs are case-sensitive

  7. Stack Not Complete

  8. Wait for CREATE_COMPLETE status

  9. Check CloudFormation Events tab for errors

  10. Wrong AWS Region

  11. The role must be in us-east-1
  12. Check your CloudFormation console region

See the full Troubleshooting Guide for more solutions.

Revoking Access

To revoke Vell's access at any time:

  1. Go to AWS CloudFormation console
  2. Select the vell-marketplace-role stack
  3. Click Delete
  4. Confirm deletion

The IAM role is immediately deleted and Vell can no longer access your account.

You can also revoke access from within Vell:

  1. Go to Cloud Connectors in Vell
  2. Find your AWS connection
  3. Click Revoke Access

Next Steps

Once your AWS account is connected:

Need Help?