API integrations
Add a data source yourself: get the key, store it safely, describe the connection, schedule the sync.
Three ways data arrives
Your first connections were built during deployment. Adding more follows the same three shapes, and the right one depends on what the source system offers.
| Type | What it is | Best when |
|---|---|---|
| API | A secure automated link to a system you already pay for: QuickBooks, Salesforce, BambooHR, and hundreds more. Fresh numbers arrive on a schedule with no manual export. | The vendor offers one and you can get a key. This is the goal for anything you look at weekly. |
| CSV | A spreadsheet export dropped into a folder the box watches. | One-time analysis, or a system with no API. Reliable and manual. |
| SQL | A read-only connection straight to a database. | Custom applications, data warehouses, and anything on-premises. Read-only means no risk of edits to the source. |
This page covers the API route. For CSV and SQL, ask your coach: those often involve network access your IT team controls.
Step 1: Get the API key
An API key is a long random string the vendor issues that proves requests are coming from you. Getting one is usually four clicks in the vendor's admin area, and the details differ per vendor. Three things matter regardless of which one you are on.
Create it under a service account, not your own login
A key tied to a person stops working the day that person leaves. Create a dedicated account named something like rapiddashboard-integration and issue the key from there.
Give it read-only scope
Most vendors let you choose what a key can do. Pick read. A key that can only read cannot damage the source system no matter what goes wrong downstream.
Copy it once and treat it like a password
Most vendors show a key exactly once. Put it straight into your password manager. Sending it over email or chat means it lives in those systems forever.
An API key is a credential, and it belongs in a password manager. Anyone holding it can read whatever the key permits. If a key does end up somewhere it should not be, revoke it at the vendor and issue a new one. That takes two minutes and completely closes the exposure.
Confirm with your coach Whether RapidDashboard also issues keys of its own for your deployment, for example to let another system pull data out of your box, and where you would generate one. This page covers keys for reading into the box.
Step 2: Store it safely
Never paste a key into a prompt. Anything you type into a chat becomes part of that conversation's history. Put the key on the box through a terminal, then tell the agent the name of the setting rather than its value.
Connect to the box and open your workspace configuration:
ssh rapidbox cd /opt/stacks/<your-client-code>-app nano .env
Add a line naming the credential. Use a clear, uppercase name so it is obvious later what it belongs to:
QUICKBOOKS_API_KEY=paste-the-real-key-here
Save with Ctrl + O then
Enter, and exit with Ctrl +
X. The .env file stays on the box and is excluded from version
control, so the key never travels with your code.
Now you can talk about the key by name without ever repeating its value:
I have added a credential to this workspace's .env as QUICKBOOKS_API_KEY. Read it from the environment when you build the integration. Never print it, never write it into a file that gets committed, and never include it in your response to me.
Confirm with your coach Whether your deployment stores integration credentials in the workspace .env as shown here or in a separate managed secret store. The steps above are the general pattern, and your box may be configured with something tighter.
Step 3: Describe the integration
With the key stored, the build is a conversation. Say what system, what data, how often, and what you plan to do with it.
Add a new data source to this box. System: <vendor name, for example QuickBooks Online> Credential: already stored in .env as <YOUR_KEY_NAME>. Read it from the environment and never print it. Pull these records: - <for example: invoices, customers, and payments> - covering <for example: the last 24 months, then keep current> Requirements: - read only, change nothing in the source system - store the results in our own data store so dashboards query locally rather than hitting the vendor every time a page loads - record when each sync ran, how many records changed, and any errors - handle the vendor's rate limits and retry sensibly rather than failing the whole run - if a record is deleted at the source, mark it inactive here rather than removing it Before you build: 1. Check the vendor's current API documentation and tell me which version you are targeting 2. Tell me what you will pull, what you will skip, and why 3. Tell me anything you need from me that you cannot determine yourself Then build it, run one sync limited to <30 days> of data, and show me what came back.
Ask for a small first sync. Thirty days of data proves the connection, the field mapping, and the error handling, and it finishes while you are still watching. Widen the window once it looks right.
Step 4: Test it before you trust it
A sync that returns rows is a sync that works. A sync that returns the right rows takes one more conversation.
Validate the <vendor> integration before I build anything on it. 1. Show me the record counts by month for what you pulled, and tell me whether any month looks suspiciously light 2. Pick five records at random and show me the full detail, so I can open the same five in <vendor> and compare 3. Total <the key figure, for example total invoiced> for <a month I can check> so I can tie it to a report I already trust 4. Tell me which fields you mapped to which of our concepts, and which fields you ignored 5. Tell me what happens on the next sync when a record has changed at the source, and what happens when the vendor is unreachable Change nothing. I want to check it before we go further.
Do the tie-out in point three properly. Getting one month to agree with a report your finance team already signs off on is what makes every future dashboard from this source believable.
Step 5: Schedule the sync
Choose a refresh rate based on how a stale number would change a decision. Most sources do not need to be current to the minute, and every sync costs an API call against your vendor's limits.
| Refresh | Good for |
|---|---|
| Every 15 minutes | Operational screens someone watches during the working day: dispatch, order status, support queues. |
| Hourly | Sales pipeline, inventory, anything reviewed several times a day. |
| Nightly | Financials, payroll, most reporting. The default for a reason. |
| Weekly | Slow-moving reference data: price lists, org charts, product catalogs. |
Put the <vendor> sync on a schedule. Run it <nightly at 2am / hourly / every 15 minutes> in our local timezone. Then set up monitoring: - record every run with start time, duration, record counts, and outcome - if a run fails, retry <twice> before giving up - if it still fails, notify <who and how> - if a run has not succeeded in <24 hours>, treat that as a failure too, because a sync that silently stops is worse than one that errors Build me a small status page showing every data source, when it last synced successfully, and whether it is currently healthy. Then tell me where the schedule is configured so I can change it myself.
The status page is worth the five minutes. The failure mode that costs you credibility is a dashboard showing confidently stale numbers. One page telling you every source is current turns that from a discovery into a glance.
Where common systems keep their keys
Vendors move their settings around, so treat this as a starting point rather than a map. Search the vendor's help center for "API key" or "developer settings" when a menu has moved.
| System | Usually found under | Watch for |
|---|---|---|
| QuickBooks Online | The Intuit developer portal, as an app you create | Uses OAuth rather than a simple key. Your coach can handle the first connection. |
| Salesforce | Setup → App Manager → connected app | Needs an admin. API access depends on your edition. |
| HubSpot | Settings → Integrations → Private apps | Choose read scopes only. |
| BambooHR | Your profile menu → API keys | The key inherits that user's permissions, so use a service account. |
| Shopify | Settings → Apps and sales channels → Develop apps | Scopes are granular. Grant only what the dashboard needs. |
| Stripe | Developers → API keys | Use a restricted key with read access, not the secret key. |
| Microsoft 365 | Entra ID app registration | Almost always needs your IT administrator. |
| An in-house system | Ask whoever maintains it | A read-only SQL connection is often simpler than building an API. |
Connections are the trickiest step, and we expect to help. Call 608-783-8324 and we will walk through your specific system on a screen share. Most take under fifteen minutes once someone with admin rights is on the call.
Rotating and revoking
Three moments call for a new key. All three follow the same two steps: issue the new one, then revoke the old.
- Someone with access leaves. Rotate every key they could have seen.
- A key ends up somewhere it should not be. An email, a screenshot, a chat message. Revoke immediately, then issue a replacement.
- On a schedule. Annually is a common policy. Ask your IT team whether yours has one.
I have issued a new API key for <vendor> and updated <YOUR_KEY_NAME> in the .env on this box. Confirm the integration still works by running one sync limited to the last 7 days, and tell me the result. Do not print the key. Then tell me whether anything else on this box still references the old credential.
Once that sync succeeds, revoke the old key at the vendor. Leaving a working key in place with nothing using it is the exposure you are trying to remove.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
401 or "unauthorized" |
The key is wrong, expired, or revoked. | Re-copy it from the vendor and update .env. Watch for a trailing space when pasting. |
403 or "forbidden" |
The key is valid and lacks permission for that data. | Add the read scope at the vendor for the records you need, then retry. |
429 or "rate limit" |
Too many requests too quickly. | Ask the agent to slow the sync and add backoff. Also reconsider whether you need this source every fifteen minutes. |
| Sync succeeds, dashboard is empty | Data landed under different field names than the dashboard expects. | Ask: "Show me the field mapping between the raw |
| Numbers disagree with the vendor's own report | A filter or date-basis difference, almost always. | Ask for the query and the underlying records for one month, then compare line by line. |
| It worked, then quietly stopped | A key expired, or the vendor changed their API version. | This is what the status page in Step 5 is for. Check it first, then check the vendor's changelog. |
Talk to a human instead.
Every RapidDashboard client gets direct access to the team that built the box. Most questions take under ten minutes on a call.