Skip to main content
This quickstart runs a native integration end to end. You will create a customer, connect their third-party app, write data into that app from your backend, and see what it takes to go live. Plan about 15 minutes. By the end you will have connected a real account and created a record in the connected app through Refold, the same loop your product will run for every customer.

​
Prerequisites

  • A Refold account. Log in at app.refold.ai. Don’t have one? Contact us to get set up.
  • An app to integrate. This guide uses HubSpot (hubspot) as the example. Any connector works; swap the slug and action names to match yours.
  • A backend that can make HTTP calls. Every example here is a curl you can run from a terminal, then move into your server.
Every API call uses the base URL https://app.refold.ai and sends your API key in the x-api-key header. Account-scoped calls also send the customer’s linked_account_id as a header. Never expose your API key in the browser.

​
Step 1: Get your API key

1

Open Settings > Credentials

In the Refold Console, go to Settings > Credentials.
2

Export your key

Copy your API key and export it so the commands below can read it.
export REFOLD_API_KEY="your-api-key-here"

​
Step 2: Configure the app

Before a customer can connect an app, tell Refold how to authenticate with it.
1

Open the app settings

Go to Apps > HubSpot > Settings.
2

Set the auth method

Choose OAuth 2.0 and either add your own client ID and secret or select Use our credentials to test with Refold’s. For key-based apps, add the API key instead. Click Save.
Not ready to use a real app? Configure the built-in Playground app (playground_app) the same way and run the rest of this guide against it.

​
Step 3: Create a linked account

A linked account represents one of your customers. You choose its linked_account_id and reuse that id in every account-scoped call. Create one per customer, typically when they sign up.
cURL
curl -X POST https://app.refold.ai/api/v2/public/linked-account \
  -H "x-api-key: $REFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linked_account_id": "demo-user-1",
    "name": "Demo User"
  }'
Output
{ "success": true }

​
Step 4: Connect the app

Your customer authorizes the app from your product. The fastest way to see it work is the hosted Connect portal: generate a URL for the linked account and open it.
cURL
curl -X POST https://app.refold.ai/api/v2/public/connect-url \
  -H "x-api-key: $REFOLD_API_KEY" \
  -H "linked_account_id: demo-user-1" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Demo User" }'
Output
{ "hosted_url": "https://app.refold.ai/connect/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
1

Open the portal

Open the hosted_url from the response in your browser.
2

Connect HubSpot

Find HubSpot, click Connect, and complete authentication. A Connected tag appears when it succeeds.
To embed the flow inside your product instead of redirecting, mint a session token for the linked account on your backend and pass it to the React SDK. The token authenticates the frontend so your API key stays server-side.

​
Step 5: Write data to the connected app

This is the payoff. With the account connected, write data straight into the customer’s HubSpot from your backend by executing an action. Refold uses the stored credentials automatically, so no app tokens go in the request. First, confirm the action you want exists for the app:
cURL
curl https://app.refold.ai/api/v2/integration-schema/hubspot/actions \
  -H "x-api-key: $REFOLD_API_KEY" \
  -H "linked_account_id: demo-user-1"
Then execute it. Here you create a contact in the customer’s HubSpot:
cURL
curl -X POST https://app.refold.ai/api/v2/integration-schema/hubspot/actions/create_contact/execute \
  -H "x-api-key: $REFOLD_API_KEY" \
  -H "linked_account_id: demo-user-1" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstname": "Jane",
    "lastname": "Doe"
  }'
Output
{
  "success": true,
  "data": {
    "id": "1510721",
    "createdAt": "2026-06-21T10:04:11.000Z"
  }
}
Open the customer’s HubSpot. The contact Jane Doe is there. You just wrote data to an external system through Refold.
Write actions (create, update, delete) make real changes in the connected app. Test with a read action such as get_contact first, and use a sandbox account while you build.
For multi-step logic (read, transform, then write, or fan out to several apps), run a workflow instead of a single action.

​
Step 6: Go live

You have run the full loop in test. To take it to production:
1

Switch to your production environment

Generate a production API key in Settings > Credentials and use real OAuth credentials for the app, not the shared test ones.
2

Embed the connect flow in your product

Replace the hosted portal with the React SDK or a build-your-own flow so customers connect without leaving your app.
3

Handle connection health

Subscribe to webhooks and surface connection status so customers can reconnect when a token expires.
4

Run the go-live checklist

Walk the go-live checklist before your first customer.

​
Next steps

Embed the connect flow

Bring the connection experience into your own UI.

Configure the integration

Collect customer input with config fields and field types.

Move data

Read, write, and sync data between your app and connected systems.

Recipes

Follow end-to-end builds for NetSuite, Salesforce, and Workday.