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.
Create an API key
Section titled “Create an API key”- In the Jetstack app, open Settings → Access Tokens.
- Create a key, give it a name you’ll recognise later, and choose its scopes (or a preset).
- Optionally set an expiry date. Keys without one stay valid until you revoke them.
- 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.
Send the key
Section titled “Send the key”Pass the key as a bearer token on every request:
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:
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.
Scopes
Section titled “Scopes”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.
| Scope | Allows |
|---|---|
portals:read | List connected HubSpot portals |
hubspot:browse | Read assets and workflow profiles live from a connected portal |
hubspot:import | Import assets from a portal into your library |
hubspot:deploy | Get mapping requirements and deploy library assets to a portal |
assets:read | Read assets, profiles and workflow diagrams in your library |
modules:read | Read modules |
tasks:read | Follow import and deploy tasks |
audit:read | Read audit blocks, templates, runs and results |
audit:write | Create audit templates and start audit runs |
projects:read | Read Projects and everything in them: portal, documents, knowledge, blueprint, assets, runs, deploy log and credits |
projects:write | Start and manage chats, answer or decline cards, resolve knowledge decisions, rescan the portal and verify assets |
projects:chat | Send chat messages and upload documents |
projects:generate | Approve plan cards (which builds the assets), analyze documents, suggest resolutions, derive a blueprint, repair or restore assets and resume paused runs |
projects:deploy | Approve deploy and fix cards, and retire assets, including removing them from the client’s portal |
projects:admin | Create, rename and archive Projects, bind the portal and manage members |
projects:billing | Buy Projects credits |
Presets
Section titled “Presets”| Preset | Includes |
|---|---|
| Read-only | assets:read, modules:read, tasks:read, portals:read, mapping:read, audit:read, projects:read |
| Operator | Everything in Read-only, plus assets:write, modules:write, hubspot:browse, hubspot:import, hubspot:deploy, mapping:validate, audit:write |
| Full access | Every 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.
Projects permissions
Section titled “Projects permissions”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.
Rate limits
Section titled “Rate limits”Each key can make 5 requests per second and 100 requests per minute. Responses report your remaining quota:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed in the current window |
RateLimit-Remaining | Requests left in the window |
RateLimit-Reset | Seconds until the window resets |
Retry-After | On 429 responses: seconds to wait before retrying |
Errors
Section titled “Errors”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"}| Status | Code | What to do |
|---|---|---|
| 401 | AUTH_TOKEN_MISSING | Send the Authorization: Bearer … header |
| 401 | AUTH_TOKEN_INVALID | Use the Bearer scheme and a key that starts with jsai_ |
| 401 | API_KEY_NOT_FOUND | Check the key was copied correctly and belongs to this instance |
| 401 | API_KEY_EXPIRED | Create a new key |
| 401 | API_KEY_REVOKED | Create a new key |
| 403 | API_KEY_INSUFFICIENT_SCOPE | Add the scope the endpoint lists to the key |
| 429 | API_KEY_RATE_LIMITED | Wait for Retry-After seconds, then retry |
Include the requestId when you contact support about a failed request.