---

name: ramp-security-basics description: >- Establish least-privilege OAuth, secret, webhook, data, card, and financial-write controls for a Ramp integration. Use when threat modeling, reviewing a launch, or remediating controls. Trigger with "secure Ramp integration" or "Ramp security review". allowed-tools: Read,Glob,Grep,Write,Edit version: 2.0.0 argument-hint: "[integration-or-environment]" model: inherit effort: high author: Jeremy Longshore jeremy@intentsolutions.io license: MIT compatibility: Requires current Ramp Developer API documentation and approved access for any live financial, card, identity, accounting, application, or configuration change tags: [saas, ramp, security, secrets, threat-modeling]

Ramp Integration Security Baseline

Overview

Protect credentials and financial authority as separate assets. Minimize scopes and data paths, verify webhook authenticity from raw bytes, and require idempotent, approved, reconciled writes.

Prerequisites

• Identify the Ramp application, environment, business entities, affected data and workflows, accountable owner, and rollback boundary.
• Read references/official-docs.md and re-check endpoint schemas, scopes, limits, and support status before a live operation.
• Use synthetic fixtures or Ramp sandbox until production access and business effects are explicitly approved.
• Prepare approved secret storage and a sanitized evidence location.

Current Contract

• Ramp access tokens are opaque bearer credentials bound to environment and scope; they must not be logged or exposed to browser code.
• Webhook subscriptions return a secret and deliveries include X-Ramp-Signature, an HMAC-SHA256 signature over the exact raw request body.
• Embedded Cards can keep PAN/CVV outside application servers; Vault brings card data into the backend and requires production approval.
• Authorization Code flows require strong state verification and exact redirect URIs; Client Credentials is for internal server-side integrations.

Instructions

1. Threat-model clients, redirects, token exchange, secret stores, API adapters, webhook ingress, queues, logs, card delivery, accounting writes, admin access, and support paths.

2. Split applications by trust boundary, request minimum scopes, isolate environments and tenants/entities, and assign rotation plus emergency revocation owners.

3. Verify webhook signatures over raw bytes before parsing, validate expected event type and business, deduplicate by event ID, and process asynchronously.

4. Prefer embedded card delivery; isolate any approved Vault service and prohibit PAN/CVV from logs, queues, analytics, support tools, and general databases.

5. Test stolen-token containment, replay, cross-tenant/entity denial, redirect/state failure, secret rotation, webhook-secret rotation, and financial-write reconciliation.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Security owns client and secret controls; privacy/data owners approve fields; finance/business owners approve write authority; Ramp approves restricted production card surfaces.

Output

A threat model, client/scope matrix, secret inventory, webhook verification design, card-data boundary, write-control ledger, test receipts, and incident contacts.

Error Handling

Condition	Response
Signature verification fails after JSON parsing	Capture and verify the exact raw body before any parser or middleware mutation.
A secret appears in source or logs	Revoke and rotate, restrict evidence, remove downstream copies, and add prevention tests.
A read client can write	Revoke or replace its token, narrow scopes/application design, and add a negative test.

Examples

Example 1

Secure a webhook receiver with raw-body HMAC verification, stable event-ID dedupe, tenant checks, and a durable queue.

Example 2

Move card display to Ramp's hosted iframe and prove the backend no longer receives card details.

Validation

• Every credential and write capability has minimum scope, owner, rotation, revocation, and negative tests.
• Webhook authenticity and replay controls operate before business processing.
• Secrets and card details are absent from routine storage and telemetry.
• Cross-environment, cross-tenant, cross-entity, and over-scope access fail.

Resources

• Official documentation and contract notes
• Re-check the dated contract and current OpenAPI schema before any live request.
• Treat unresolved vendor behavior, authority, or financial state as a stop condition.