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.mdand 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
-
Threat-model clients, redirects, token exchange, secret stores, API adapters, webhook ingress, queues, logs, card delivery, accounting writes, admin access, and support paths.
-
Split applications by trust boundary, request minimum scopes, isolate environments and tenants/entities, and assign rotation plus emergency revocation owners.
-
Verify webhook signatures over raw bytes before parsing, validate expected event type and business, deduplicate by event ID, and process asynchronously.
-
Prefer embedded card delivery; isolate any approved Vault service and prohibit PAN/CVV from logs, queues, analytics, support tools, and general databases.
-
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.