Docs

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 EngineCloud At launch

View as Markdown
On this page
  1. Project
  2. Environment
  3. Ingest key
  4. API token
  5. Root token
  6. Which credential goes where
  7. Engine and Cloud: who creates what
  8. Example: the shop

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 doSend events, replay recordings and page snapshots to its project.
What it cannot doRead anything. Change anything. Reach another project.
Where it livesIn 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 manyOne 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.

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.

ScopeWhat it addsTypical holder
readRead 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.
replayRead replay recordings and page snapshots: what a person saw on their screen.A coding agent that should read replays. A person using the Console.
ciRegister 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.
adminChange 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.

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 upUseWhy
The browser SDKAn ingest keyIt only needs to send.
The Node or Next.js SDKAn ingest keySame.
An OpenTelemetry exporterAn ingest keySame. See OpenTelemetry.
Your coding agent, through MCPAn API token with read, plus replay if it should read replaysIt reads, and can mark a problem resolved once it has fixed it. See MCP authentication.
Source map upload in CIAn API token with ciIt registers the release and uploads its source maps, and can do nothing else. See Source maps in CI.
The CLI on your own machineAn API token, or the root token on a self-hosted engineSee the CLI reference.

Engine and Cloud: who creates what

The Sypnia engine and Sypnia Cloud compared
Sypnia engineOpen source, self-hostedSypnia CloudPaid service, with a free tier
Who gets inWhoever 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 projectWith 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 tokensWith 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 dataThe 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. The exact calls and commands are in the API reference and the CLI reference.

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.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close