Portals and keys
A portal is a HubSpot account you want to read from or deploy into. You can connect up to 50. Each has its own page with its keys, snapshots, deployed items and recent jobs.
Adding a portal
Section titled “Adding a portal”Click + Add portal in the sidebar. Two fields:
| Field | What to enter |
|---|---|
| HubSpot portal ID | The number HubSpot shows under your account name in the top right. Also called the Hub ID. |
| Name | Anything you will recognise, e.g. “Acme sandbox”. |
A portal can be connected once. Its page then shows the steps Portal · Personal Access Key · Snapshot access · Snapshot until a Private App Token is saved.
The two keys
Section titled “The two keys”Both are optional, and you can save either or both. They are checked with HubSpot when saved, stored AES-256-GCM encrypted, and only ever shown back masked.
| Private App Token | Personal Access Key | |
|---|---|---|
| What it is | A HubSpot private app access token or service key. Starts with pat-. | A HubSpot Personal Access Key. Starts with pak-. |
| Used for | Reading the portal for snapshots. Creating assets when you deploy a recipe or snapshot. | Installing Trading Cards apps through the HubSpot CLI, including TC-Snapshots. Nothing else. |
| Needed for | Take a snapshot, Deploy assets | Deploy an app, Install TC-Snapshots |
| How to get one | Install TC-Snapshots (recommended, below), or paste a Private App Token or service key you made yourself. | app.hubspot.com/l/personal-access-key |
Save the Personal Access Key first: it is what installs TC-Snapshots. A key that belongs to a different portal is refused with the portal it does belong to.
Snapshot access with TC-Snapshots
Section titled “Snapshot access with TC-Snapshots”A complete snapshot can use more than fifty scopes. Rather than ticking them by hand on a private app, install TC-Snapshots: a private app that declares every scope a snapshot or deploy can use and then hands its own access token to Trading Cards. Under Private App Token on the portal’s page:
- Install the app into this portal. Pick a platform version and click Install TC-Snapshots. It uploads as a developer project through the Personal Access Key, like any app in the library, and shows on Activity.
- Install the app in HubSpot and confirm its scopes. Open in HubSpot lands on the project’s Distribution tab. Click Install app, review the scopes, confirm. This needs a super admin.
- Connect. Click Get a pairing code. In HubSpot, open TC-Snapshots from the Marketplace menu (or from the project’s page), enter the code on its home page and click Connect. The app sends the code and its token to Trading Cards; the portal page notices within a few seconds and the Private App Token row shows the saved key.
| Platform version | Offered as | Note |
|---|---|---|
| 2026.09 | Stable (default) | |
| 2027.03-beta | Beta | The portal must have the Developer Platform beta enabled, or the upload is refused. |
Scopes every tier has are required by the app; the rest are optional, so HubSpot drops any the portal’s tier cannot grant instead of refusing the install. Why N scopes? on the page lists each scope and the asset types that need it.
The pairing code works once, for one portal, for ten minutes. The token never passes through your browser or clipboard: it goes from the app’s serverless function to Trading Cards, which checks it with HubSpot and refuses it unless it belongs to the portal the code was issued for.
Paste a key on the same row is the manual route: a Private App Token or service key you created yourself, checked and stored the same way.
Scopes
Section titled “Scopes”HubSpot tells the app which scopes a key has. The portal page shows the count and when it was last read. Scopes are read again:
- when you click Scan scopes on the key’s row,
- when the snapshot wizard reaches its Access step,
- before every deploy, in the preflight.
Snapshots check read scopes; deploys check write scopes. Anything a key cannot do is listed with the scope it needs, with Copy scopes so you can paste them into HubSpot. Broad legacy scopes such as hubdb, files, tickets and content count as covering the granular scopes they imply.
Managing keys
Section titled “Managing keys”On a saved key’s row: Scan scopes, Replace, Remove. Removing a key deletes it from Trading Cards. Revoking it in HubSpot has the same effect from HubSpot’s side.
Disconnecting a portal
Section titled “Disconnecting a portal”The ⋯ menu on the portal page has Disconnect. Its saved keys, install history, snapshots and jobs are removed from Trading Cards. Apps already deployed stay in the portal.