# Projects, environments, keys and tokens

> Where your data belongs in Sypnia, and exactly what an ingest key, an API token and the root token can and cannot do.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/concepts/projects-keys-and-tokens/

This page is for whoever sets Sypnia up: it explains where data belongs and who can reach it. Projects, environments, ingest keys and API tokens work the same way in the open-source engine and in Sypnia Cloud. What differs is who creates them, which the last section covers.

## Project

A project is one app that Sypnia watches. Every event, session, problem, release and uptime check belongs to exactly one project, and nothing is shared between projects. Every row in the database and every object in storage carries its project.

Use one project per app, even when the app has several parts. The shop's web frontend and its API both send to the project `shop`. That is what lets Sypnia follow one request from the click to the database: a trace connects parts of the same project only.

Use separate projects for separate apps, for example the shop and its back office.

## Environment

An environment says where a build of your app runs: `production`, `staging`, `development`, or any name you choose. Your app sets it when it starts the SDK. If it sets nothing, the environment is `production`.

You do not create environments. One exists as soon as an event arrives with its name. A project has at most 20 environment names: an event that carries a twenty-first is dropped, and the answer from ingest counts it.

Environments keep data apart inside a project:

- Sessions, problems, traces and performance numbers are always shown for one environment at a time.
- The same failure in `development` and in `production` is two problems, one in each.
- **Alerts and the daily summary only cover `production`.** Your own testing does not wake you up.
- On Sypnia Cloud, plan limits count all environments of a project together.

## Ingest key

An ingest key is how your app proves which project it sends to. It starts with `spk_`.

|                   |                                                                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| What it can do    | Send events, replay recordings and page snapshots to its project.                                                                             |
| What it cannot do | Read anything. Change anything. Reach another project.                                                                                        |
| Where it lives    | In your app's code: the browser SDK, the server SDK, or an OpenTelemetry exporter.                                                            |
| Is it secret?     | No. It is public by design and safe to ship in a browser.                                                                                     |
| How many          | One or more per project, up to 20 that are not revoked. Give each app or platform its own, so you can revoke one without stopping the others. |

Because the key is public, anyone who reads your page's source can send events to your project with it. Sypnia limits the damage in four ways:

- The key can only write.
- Ingest checks the shape and size of everything it receives.
- Limits apply to each key and each project. A key accepts 600 requests a minute from one address unless you give it another number.
- A project can list the **origins allowed** to send browser data, for example `https://yourapp.com`. While the list is empty, any origin is accepted. Requests without an origin, such as those from your server, are always accepted.

If a key is abused, revoke it and create another. At launch the ingest key is the only credential for sending. A signed identity, for apps that need proof of who is sending, is [planned](https://docs.sypnia.com/reference/planned).

**To rotate a key** without losing data: create a second key, deploy your app with it, then revoke the first. A revoked key is refused within one minute.

## API token

An API token reads your project's data, through the HTTP API, the CLI and the MCP server. It starts with `sps_`. It is a secret: treat it like a password.

A token belongs to one project and carries one or more scopes.

| Scope    | What it adds                                                                                                                                                                                                                                                                       | Typical holder                                                       |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `read`   | Read problems, the sessions list and each session's timeline, traces, performance numbers, uptime results, releases and alerts. Its only changes are marks that can be undone and are recorded: resolve or reopen a problem, acknowledge an alert, set the status of a suggestion. | Your coding agent through MCP. A script.                             |
| `replay` | Read replay recordings and page snapshots: what a person saw on their screen.                                                                                                                                                                                                      | A coding agent that should read replays. A person using the Console. |
| `ci`     | Register releases and upload source maps, and nothing else. It cannot read data and cannot change settings, so the secret you store in a CI system is worth little to anyone who finds it.                                                                                         | Your CI.                                                             |
| `admin`  | Change everything else: create and revoke keys and tokens, change project settings, manage uptime checks, alert rules and webhooks, ignore a problem, ask for a new analysis or a pull request, delete data. It can also do what `ci` does.                                        | You.                                                                 |

Apart from that, scopes do not include each other. A token that should read and manage needs `read` and `admin`; a token for CI that only uploads source maps needs `ci` alone.

Rules that hold for every token:

- It is shown once, when it is created. Sypnia stores only a hash of it and cannot show it again.
- It does not expire unless you give it an expiry date when you create it. It works until that date or until you revoke it, and a revoked token is refused within one minute.
- A project has at most 50 tokens that are not revoked.
- It cannot send events. Sending is the ingest key's job.
- Without the `replay` scope, a token can see that a session has a replay but cannot read it.

Give each tool its own token with the fewest scopes it needs. If your coding agent's token leaks, you revoke that one and nothing else stops.

## Root token **\[Engine]**

A self-hosted engine has one more credential: the root token. You choose it, a string of 32 characters or more, and set it in the environment when you install the engine (`SYPNIA_ROOT_TOKEN`). See the [configuration reference](https://docs.sypnia.com/self-hosting/configuration).

The root token can do everything on every project, including the two things no API token can do: create a project and delete one. Use it to create your projects and their first tokens, then put it away. Do not give it to an app, a coding agent or a CI job. To change it, change the setting and restart the engine.

Sypnia Cloud has no root token. People sign in instead.

## Which credential goes where

| You are setting up             | Use                                                               | Why                                                                                                                                                       |
| ------------------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The browser SDK                | An ingest key                                                     | It only needs to send.                                                                                                                                    |
| The Node or Next.js SDK        | An ingest key                                                     | Same.                                                                                                                                                     |
| An OpenTelemetry exporter      | An ingest key                                                     | Same. See [OpenTelemetry](https://docs.sypnia.com/sdks/opentelemetry).                                                                                    |
| Your coding agent, through MCP | An API token with `read`, plus `replay` if it should read replays | It reads, and can mark a problem resolved once it has fixed it. See [MCP authentication](https://docs.sypnia.com/mcp/authentication).                     |
| Source map upload in CI        | An API token with `ci`                                            | It registers the release and uploads its source maps, and can do nothing else. See [Source maps in CI](https://docs.sypnia.com/guides/source-maps-in-ci). |
| The CLI on your own machine    | An API token, or the root token on a self-hosted engine           | See the [CLI reference](https://docs.sypnia.com/cli).                                                                                                     |

## Engine and Cloud: who creates what

|                          | Sypnia engine (open source, self-hosted)                              | Sypnia Cloud (paid service, with a free tier)                                  |
| ------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Who gets in              | Whoever holds a token. There are no users and no organizations.       | People with an account, who belong to an organization and have a role.         |
| Creating a project       | With the root token, through the CLI or the API. As many as you want. | In the app, by an owner or an admin. The plan sets how many.                   |
| Creating keys and tokens | With the root token, or an API token with the admin scope.            | In the app, by an owner or an admin. Also through the API with an admin token. |
| Reading data             | The Console, the API, the CLI and MCP, each with an API token.        | The app after signing in. The API and MCP with an API token.                   |

Roles on Sypnia Cloud are described in [Organizations and teams](https://docs.sypnia.com/cloud/organizations-and-teams). The exact calls and commands are in the [API reference](https://docs.sypnia.com/api/projects-keys-and-tokens) and the [CLI reference](https://docs.sypnia.com/cli).

## Example: the shop

The shop has one project, `shop`, with two environments, `production` and `development`.

- The web frontend and the API server each use an ingest key. They could share one; two keys mean one can be rotated without touching the other.
- Cursor is connected through MCP with an API token that has `read` and `replay`.
- The CI job that uploads source maps after each deploy has its own token with `ci`.

When the Pay button breaks in production, it becomes a problem in `shop` / `production`. The same bug seen while testing in `development` is a separate problem there, and sends no alert.
