Skip to content

Authentication

Every request to https://api.jetstack.ai is authenticated with an API key. The same key signs in the CLI and the MCP server.

  1. In the Jetstack app, open Settings → Access Tokens.
  2. Create a key, give it a name you’ll recognise later, and choose its scopes (or a preset).
  3. Optionally set an expiry date. Keys without one stay valid until you revoke them.
  4. Copy the key. It starts with jsai_ and is shown once, so store it in a secret manager.

You can revoke a key from the same page at any time. A revoked key stops working immediately.

Pass the key as a bearer token on every request:

Terminal window
curl https://api.jetstack.ai/v1/portals \
-H "Authorization: Bearer jsai_your_api_key"

The Instance ID (dedicated instances only)

Section titled “The Instance ID (dedicated instances only)”

If your organization runs on a dedicated Jetstack instance, also send its Instance ID, shown under Settings → Access Tokens → Connection Details:

Terminal window
curl https://api.jetstack.ai/v1/portals \
-H "Authorization: Bearer jsai_your_api_key" \
-H "X-Instance-Id: your-instance-id"

Everyone else can leave the header out. Requests without it, or with X-Instance-Id: default, go to the main Jetstack platform.

Each key carries scopes, and every endpoint in the API reference lists the scope it needs. A request without the right scope returns 403 API_KEY_INSUFFICIENT_SCOPE.

ScopeAllows
portals:readList connected HubSpot portals
hubspot:browseRead assets and workflow profiles live from a connected portal
hubspot:importImport assets from a portal into your library
hubspot:deployGet mapping requirements and deploy library assets to a portal
assets:readRead assets, profiles and workflow diagrams in your library
modules:readRead modules
tasks:readFollow import and deploy tasks
audit:readRead audit blocks, templates, runs and results
audit:writeCreate audit templates and start audit runs
projects:readRead Projects and everything in them: portal, documents, knowledge, blueprint, assets, runs, deploy log and credits
projects:writeStart and manage chats, answer or decline cards, resolve knowledge decisions, rescan the portal and verify assets
projects:chatSend chat messages and upload documents
projects:generateApprove plan cards (which builds the assets), analyze documents, suggest resolutions, derive a blueprint, repair or restore assets and resume paused runs
projects:deployApprove deploy and fix cards, and retire assets, including removing them from the client’s portal
projects:adminCreate, rename and archive Projects, bind the portal and manage members
projects:billingBuy Projects credits
PresetIncludes
Read-onlyassets:read, modules:read, tasks:read, portals:read, mapping:read, audit:read, projects:read
OperatorEverything in Read-only, plus assets:write, modules:write, hubspot:browse, hubspot:import, hubspot:deploy, mapping:validate, audit:write
Full accessEvery scope except projects:deploy and projects:billing

Presets also include assets:write, modules:write, mapping:read and mapping:validate, which no public endpoint currently requires.

projects:deploy and projects:billing are never part of a preset. One changes the client’s live HubSpot portal and the other buys credits, so they must be added to a key on purpose.

On the Projects API a request needs both the right scope and the right role on that Project. A key can never do more than the person who created it. GET /v1/projects/{projectId}/access returns exactly what your key can do on a Project. See the Projects API guide.

Each key can make 5 requests per second and 100 requests per minute. Responses report your remaining quota:

HeaderMeaning
RateLimit-LimitRequests allowed in the current window
RateLimit-RemainingRequests left in the window
RateLimit-ResetSeconds until the window resets
Retry-AfterOn 429 responses: seconds to wait before retrying

Errors are RFC 7807 problem documents with a stable code. Match on the code, not the message:

{
"type": "https://api.jetstack.ai/errors/api-key-not-found",
"title": "Invalid API Key",
"status": 401,
"detail": "The provided API key was not found.",
"instance": "/v1/portals",
"code": "API_KEY_NOT_FOUND",
"requestId": "req_abc123"
}
StatusCodeWhat to do
401AUTH_TOKEN_MISSINGSend the Authorization: Bearer … header
401AUTH_TOKEN_INVALIDUse the Bearer scheme and a key that starts with jsai_
401API_KEY_NOT_FOUNDCheck the key was copied correctly and belongs to this instance
401API_KEY_EXPIREDCreate a new key
401API_KEY_REVOKEDCreate a new key
403API_KEY_INSUFFICIENT_SCOPEAdd the scope the endpoint lists to the key
429API_KEY_RATE_LIMITEDWait for Retry-After seconds, then retry

Include the requestId when you contact support about a failed request.