HubSpot Service Keys of Projects-based apps: welke vervanger past bij je integratie?

Kies een HubSpot Service Key voor een integratie tussen systemen binnen één account die alleen data via de REST API nodig heeft. Kies een Projects-based app als de integratie webhooks, UI-componenten in HubSpot, lifecyclebeheer van de app of distributie nodig heeft. Voor meerdere accounts vraagt de app-route bovendien om OAuth. Bij gemengde eisen kunnen twee aparte componenten, elk met eigen beheer, de juiste keuze zijn.

Dat onderscheid doet ertoe, omdat beide routes een Bearer-token kunnen opleveren, terwijl ze verschillende architectuurproblemen oplossen. Uit het tokenformaat blijkt niet of de integratie zich op events kan abonneren, een app card kan tonen, meerdere klantaccounts kan bedienen of een gecontroleerd deploymentproces kan doorlopen.

HubSpot beschrijft Service Keys als inloggegevens op accountniveau voor data-integraties, terwijl het developerplatform Projects behandelt als het framework onder versiebeheer waarmee je app-functionaliteit bouwt. Begin de keuze daarom bij wat de integratie doet, waar ze draait, wie haar gebruikt en hoeveel accounts ze moet ondersteunen.

Er is ook een kanttekening over de volwassenheid van het product. Op 16 september 2026 noemt de documentatie over Service Keys van HubSpot de functie een publieke bèta die nog actief wordt doorontwikkeld. Controleer de status, ondersteunde scopes en limieten opnieuw voordat je je voor productie vastlegt.

Deze keuze wordt makkelijker met een volledige inventaris. Heb je nog niet op een rij welke integraties op legacy private apps draaien, begin dan met de HubSpot API-auditchecklist.

Wat is in de praktijk het verschil tussen Service Keys en Projects-based apps?

Een Service Key geeft afgebakende REST API-toegang tot data in één HubSpot-account, zonder dat je een app-project hoeft aan te maken. Een Projects-based app bundelt authenticatie en app-functies in een project dat je kunt deployen. Zo'n app kan webhooks, UI-extensies, workflowacties, instellingen en distributievormen ondersteunen die een losse credential voor data niet kan bieden.

De zuiverste vergelijking is niet ‘nieuw token tegenover oud token’. Het is credential tegenover applicatie.

Het authenticatieoverzicht van HubSpot voegt binnen de app-kolom een belangrijke splitsing toe. Een app die privé wordt gedistribueerd naar één standaardaccount kan statische authenticatie gebruiken. Een app voor meerdere accounts moet OAuth gebruiken, en de distributie-instelling bepaalt dan of hij beperkt blijft tot goedgekeurde accounts of wordt voorbereid op een vermelding in de Marketplace.

Welke vragen horen de architectuurkeuze te sturen?

Neem de beslissing op zes dimensies: mogelijkheden, distributie, eventmodel, gebruikerservaring, operationeel eigenaarschap en volwassenheid van het product. Valt een vereiste mogelijkheid buiten wat een Service Key kan, dan heeft de integratie voor dat deel een app nodig. De overige dimensies bepalen vervolgens de authenticatie en de manier van beheren.

Loop deze vragen in volgorde af.

1. Gaat de integratie alleen over data? Leest of schrijft ze gewoon records via gedocumenteerde REST API's?

2. Reageert ze op events in HubSpot? Heeft ze webhook-abonnementen nodig, dan heeft ze een app nodig.

3. Voegt ze functionaliteit toe binnen HubSpot? App cards, instellingenpagina's, app-homepages en UI-extensies horen bij een Projects-based app.

4. In hoeveel HubSpot-accounts wordt ze geïnstalleerd? Bij één account past statische app-authenticatie. Meerdere accounts vragen om OAuth.

5. Heeft ze een releaseproces als applicatie nodig? Projectconfiguratie, code review, builds die je kunt deployen en controle over de lifecycle van functies wijzen richting Projects.

6. Wie is eigenaar van de credentials en het beheer? Die eigenaar moet scopes kunnen toekennen, secrets kunnen roteren, logs kunnen onderzoeken, wijzigingen kunnen deployen en kunnen reageren als een afhankelijkheid verandert.

7. Kan het bedrijf leven met wijzigingen in een bètaproduct? Een Service Key kan vandaag functioneel geschikt zijn, terwijl de status als publieke bèta toch een bewuste beslissing over productierijpheid vraagt.

Beantwoord deze vragen op basis van waargenomen gedrag, code, logs en de huidige configuratie. De naam van een legacy-app, zoals ‘warehouse connector’, zegt weinig. Er kunnen webhook-abonnementen of een UI-component achter schuilgaan die na de oorspronkelijke bouw zijn toegevoegd.

Wanneer kies je een HubSpot Service Key?

Kies een Service Key als één account een afgebakende credential nodig heeft voor directe REST API-toegang en de integratie geen webhooks, UI, app-pagina's, workflowacties of distributie vereist. Zo blijft een data-integratie in een model dat je vanuit het account beheert, en hoef je geen project te bouwen alleen om API-toegang te krijgen.

Veelvoorkomende toepassingen:

• een geplande export van HubSpot naar een datawarehouse;

• een business-intelligence-pipeline die CRM-records leest;

• een intern script dat goedgekeurde eigenschappen bijwerkt;

• een nachtelijke afstemmingsjob tussen HubSpot en een intern systeem;

• een lichte automatisering die volgens een vast schema een API-endpoint bevraagt.

Service Keys kunnen worden aangemaakt en beheerd door Super Admins en gebruikers met toegang tot Developer tools. De huidige documentatie van HubSpot toont objectspecifieke scopes, requestlogs, het aanpassen van scopes, rotatie en verwijderen in het onderdeel Development. Volgens de documentatie gelden voor Service Keys ook dezelfde limieten als voor privé gedistribueerde apps op de genoemde actuele platformversies.

Het operationele voordeel is duidelijkheid. Het account heeft een eigen credential voor een benoemde datajob, en die credential kun je afbakenen en roteren zonder dat hij voor een bredere app staat. Standaard secretbeheer buiten HubSpot blijft wel nodig: bewaar de key in een goedgekeurd secrets-systeem, beperk wie er tijdens runtime bij kan, leg vast wie eigenaar is en koppel rotatie aan een geteste wijzigingsprocedure.

Kies een Service Key niet alleen omdat de huidige integratie een statisch token gebruikt. Controleer eerst wat dat token ondersteunt. Volgens HubSpot kunnen Service Keys geen webhooks, geen calls binnen een UI-extensie en geen andere functionaliteit van het developerplatform authenticeren buiten REST API-requests. Een token omwisselen brengt die mogelijkheden niet terug.

Wanneer kies je een Projects-based app?

Kies een Projects-based app als de integratie zich gedraagt als een applicatie: ze abonneert zich op events, voegt functionaliteit toe binnen HubSpot, biedt eigen workflowacties, beheert app-specifieke configuratie of moet in meerdere accounts worden geïnstalleerd. Projects bieden het configuratie- en deploymentframework om die functies als één beheerd product te draaien.

De huidige documentatie over app-configuratie van HubSpot noemt functies als webhook-abonnementen, app cards, serverless functions, app events, app objects, instellingencomponenten, eigen workflowacties en telemetrie. Welke functies precies beschikbaar zijn, hangt af van de distributie, authenticatie, platformversie, scopes en productgeschiktheid van de app.

De Projects-route splitst zich daarna op distributie:

OAuth brengt eigen operationele eisen mee. De integratie heeft een backend nodig die autorisatie start, tokendata opslaat, het verversen van tokens afhandelt en credentials aan het juiste account koppelt. Installatie en herautorisatie worden onderdeel van je support. Een statische app voor één account is eenvoudiger, maar ook daar horen broncodeconfiguratie, deployment, installatie en het beheer van de lifecycle van functies bij.

Kies dit model omdat de mogelijkheden of de distributie erom vragen, niet omdat Projects vanzelf als het geavanceerdere antwoord geldt. Een nachtelijke data-export heeft niet automatisch baat bij app cards en deploymentinfrastructuur. Andersom kun je een klantproduct dat op events draait niet terugbrengen tot een Service Key zonder het gedrag te veranderen.

Wanneer is een hybride model zinvol?

Een hybride model is zinvol als één bedrijfsoplossing uit twee afzonderlijke workloads bestaat: een applicatie die webhooks of UI-functies in HubSpot nodig heeft, en een aparte datapipeline die alleen REST API-toegang op accountniveau nodig heeft. Geef je elke workload een eigen credential en eigen grenzen, dan zijn scopes, eigenaarschap, rotatie, monitoring en incidentafhandeling vaak makkelijker te overzien.

Een revenue-operationssysteem kan bijvoorbeeld bestaan uit:

• een Projects-based app die webhooks voor contactwijzigingen ontvangt en accountcontext toont in een app card; en

• een nachtelijke warehouse-export die geselecteerde CRM-objecten leest met een Service Key.

Dit is een architectuuroptie, geen eis van HubSpot. Je krijgt er twee componenten door die je moet beheren, testen en monitoren. De scheiding loont alleen als de workloads wezenlijk verschillen in mogelijkheden, releasecycli, eigenaren of toegangsprofielen.

Doe deze test voordat je splitst:

1. Kun je elk component beschrijven als een complete workload met een benoemde eigenaar?

2. Kan elk component met minder scopes toe dan de gecombineerde integratie?

3. Kun je elk component los deployen, roteren, pauzeren en onderzoeken?

4. Vermindert de scheiding de koppeling, in plaats van bedrijfslogica te dupliceren?

5. Is het team klaar om twee credentials te monitoren en gedeeld datagedrag op elkaar af te stemmen?

Is het antwoord meestal nee, houd de oplossing dan binnen één Projects-based app. Draaien de datajob en de applicatie nu al als aparte systemen, dan sluit het hybride model mogelijk beter aan op de werkelijkheid.

Hoe kies je een vervanger voor een legacy private app?

Deel de legacy-app in op basis van de functies die je waarneemt, voordat je een vervanger kiest. Alleen data lezen en schrijven wijst richting een Service Key. Webhooks, UI-extensies, app-pagina's of andere app-functies wijzen richting Projects. Installatie in meerdere accounts voegt OAuth toe. Is het gebruik onduidelijk, blijf dan in de onderzoeksfase tot logs en code de echte grens laten zien.

Gebruik dit beslispad:

Het financiële en operationele risico zit in een verkeerd getrokken grens. Kies je een Service Key voor iets wat een app-functie is, dan kan dat een tweede herbouw afdwingen zodra de ontbrekende webhook-, UI- of distributie-eis boven water komt. Kies je Projects voor een simpele export, dan kan dat een lifecycle van code en deployment toevoegen die het beheerteam niet kan onderhouden.

Een korte technische spike is verantwoord als de documentatie een belangrijke vraag over geschiktheid of compatibiliteit niet beantwoordt. Benoem de onzekere mogelijkheid, bouw de kleinste representatieve test in een developer-testaccount, leg de uitkomst vast en gebruik dat bewijs in de beslissing. Laat een proof of concept niet uitgroeien tot de productiemigratie zonder de gebruikelijke review van scopes, beveiliging, monitoring en support.

Wat moet je controleren voordat de migratie begint?

Controleer productstatus, dekking van endpoints en scopes, geschiktheid van functies, distributielimieten, rechten, operationeel eigenaarschap en bewijs voor de overstap voordat de migratie begint. De architectuurkeuze is voorlopig tot de gekozen route het vereiste werk kan doen binnen het echte accountmodel, en tot het team de credentials, deployments, logs en herstelprocedure kan beheren.

Leg deze punten vast in de architectuurbeslissing:

• de actuele status van Service Keys, bèta of algemeen beschikbaar, en de datum waarop je dat hebt gecontroleerd;

• elk benodigd REST-endpoint en elke benodigde scope;

• elke webhook, UI-extensie, workflowactie, app-pagina of eigen functie;

• het aantal en type HubSpot-accounts waarin de integratie moet worden geïnstalleerd;

• eisen voor statische authenticatie of OAuth;

• het team dat verantwoordelijk is voor code, credentials, deployments, logs en support;

• procedures voor tokenopslag, rotatie, verlopen, intrekken en noodgevallen;

• de huidige platformversie en relevante beperkingen van functies;

• testbewijs voor datagedrag en workflows van gebruikers;

• een plan voor overstap, rollback, monitoring en uitfasering.

Volgens de huidige pagina over Service Keys van HubSpot kan een geplande rotatie de oorspronkelijke key nog zeven dagen actief houden, terwijl een noodrotatie hem direct laat verlopen. Zie dat als een productfunctie die je bij de implementatie opnieuw controleert, en ontwerp de applicatie zo dat credentials kunnen wijzigen zonder dat je code moet herschrijven.

Test bij Projects-based apps meer dan alleen de authenticatie. Controleer het build- en uploadpad, de installatie, de gevraagde scopes, de aflevering van webhooks, het gedrag van de UI, waar van toepassing de koppeling van OAuth aan accounts, en het proces om een nieuwe projectversie te deployen. Leg in je bredere portfolio van HubSpot-integraties ook per component de eigenaar en de grens van de support vast.

Het gekozen model moet passen bij hoe het bedrijf CRM-data beheert. De bredere mogelijkheden voor databeheer van HubSpot kunnen structuur en kwaliteit binnen het platform verbeteren, maar de credentials van integraties bepalen nog steeds welk extern systeem die data kan lezen of wijzigen.

Combineert je integratie datajobs, webhooks, ingebouwde UI en meerdere soorten accounts? Dan helpt Flatline je de grens tussen de mogelijkheden in kaart te brengen en om te zetten in een implementatiebeslissing. Praat met ons team voordat je het migratiepad vastlegt.

Staat de architectuur vast, dan behandelt het HubSpot API-migratieplan de volgorde, de tests en de rollback, en houdt het overzicht van HubSpots legacy-API-wijzigingen de deadlines in beeld.

De belangrijkste punten

• Een Service Key is een credential op accountniveau voor datatoegang via de REST API. Een Projects-based app is een applicatiemodel dat je kunt deployen.

• Service Keys passen bij datajobs tussen systemen binnen één account, zonder webhooks of UI-componenten in HubSpot.

• Projects-based apps passen bij integraties die op events draaien, in HubSpot zijn ingebouwd of worden gedistribueerd. Statische authenticatie werkt voor een app in één account; distributie naar meerdere accounts vraagt om OAuth.

• De juiste vervanger volgt uit de waargenomen functionaliteit, distributie, het eigenaarschap en de operationele volwassenheid, niet uit het label van de legacy-app.

• Een hybride opzet kan een datapipeline scheiden van een applicatie als de workloads verschillende scopes, eigenaren en lifecycles hebben.

• Service Keys zijn volgens de documentatie van HubSpot op 16 september 2026 nog een publieke bèta. Controleer status en limieten dus opnieuw voordat je ze in productie gebruikt.

De beste keuze is het kleinste model dat de vereiste mogelijkheden volledig ondersteunt en dat het team verantwoord kan beheren. Heb je dat model gekozen, leg dan het bewijs vast, test het doel in het echte accountpatroon en plan de migratie rond complete workflows, in plaats van het vervangen van credentials te behandelen als een losse configuratietaak.