---
title: "Authentication | Jetstack AI Docs"
description: "Authenticate with the Jetstack AI API: create API keys, choose scopes and presets, set the optional Instance ID, and handle rate limits and errors."
url: "https://jetstack.ai/docs/developers/authentication/"
---

# Authentication

Every request to `https://api.jetstack.ai` is authenticated with an API key. The same key signs in the [CLI](https://jetstack.ai/docs/developers/cli) and the [MCP server](https://jetstack.ai/docs/developers/mcp).

## Create an API key

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.

A key acts on behalf of the person who created it, inside their organization. Treat it like a password: never commit it to a repository or paste it into a client-side app.

## Send the key

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)

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.

## Scopes

Each key carries scopes, and every endpoint in the [API reference](https://jetstack.ai/api) 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

| 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

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](https://jetstack.ai/docs/developers/projects-api).

## 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

Errors are [RFC 7807 problem documents](https://datatracker.ietf.org/doc/html/rfc7807) 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.
