> Lettrove docs 1.x · https://docs.lettrove.com/docs/get-started/concepts

# How it fits together

Six ideas explain everything else in these docs. Each has one name, used the same way everywhere:
in the code, the dashboard, the API and these pages.

## Project

A **project** is one place your product uses the editor, with its own keys, allowed sites,
settings and brand. You create projects at lettrove.com in **Settings → Embed**.

A project makes one kind of design, chosen when you create it: **emails**, **landing pages**,
**popups** or **documents** (its *mode*). A product that needs two kinds uses two projects.

## Keys: publishable and secret

Each project has two kinds of key.

| Key | Looks like | Lives | Can |
|---|---|---|---|
| **Publishable** | `lt_pk_test_…`, `lt_pk_live_…` | In your page. Public by design. | Say which project the editor belongs to. Nothing else: it cannot open the editor on its own. |
| **Secret** | `lt_sk_test_…`, `lt_sk_live_…` | On your server only. | Mint tokens, read and export designs, erase people. |

A secret key is shown once, when it is made. We keep only a fingerprint of it, so we cannot show
it again; if you lose it, make a new one and revoke the old. A project can have two live secret
keys at once, so you can rotate without downtime.

## Token

The editor opens with a **token**: a short-lived pass your server mints with the secret key, for
one person, on one site.

- It lasts **15 minutes** at most (you can ask for as little as 60 seconds).
- It opens **one person's** designs, in **one project**, on **the site that asked for it**.
- The editor asks your page for a fresh one (your `getToken`) before it runs out, so an editor can
  stay open all day.
- It lives in the editor's memory only: never in a cookie or local storage. Browsers that block
  third-party cookies do not affect it.

Revoking a key or pausing a project ends every open editor of that project at once.

## Allowed sites

A project lists the **sites** its editor may appear on, such as `https://app.acme.com`. Anywhere
else, the browser refuses to show the editor at all. This is what stops someone copying your
publishable key onto their own site.

Sites are listed per environment (below). Test keys also work on `localhost` without adding it.

## End user

An **end user** is a person who uses the editor inside your product. You name them with **your own
id** for them (`user.id` when you mint a token) — a database id, a UUID, anything up to 256
characters. Their designs and images are kept under it.

Lettrove never asks for, and refuses to receive, anything else about them: no name, no email. If a
token request carries any other field, it is refused with a message naming the field. So a person
is an opaque id to us, and [erasing them](/docs/data/erasure) is one call.

## Test and live

Every key belongs to an **environment**: **test** or **live**.

| | Test | Live |
|---|---|---|
| Opens on | `localhost`, and the staging sites you add to the Test list | Only the `https` sites you add to the Live list. Never `localhost`. |
| Billed | Never | Yes |
| Release candidates of the editor | Open | Never open ([Releases](/docs/editor/releases)) |
| For | Building and testing | Your real users |

Build with test keys; switch to live keys when you launch. [Test and live keys](/docs/going-live/test-and-live)
has the checklist.

## How a session goes

```mermaid
sequenceDiagram
  participant P as Your page
  participant S as Your server
  participant G as Lettrove
  P->>S: getToken()
  S->>G: POST /embed/v1/tokens (secret key, user id, origin)
  G-->>S: token (≤ 15 min)
  S-->>P: token
  P->>G: open the editor with the publishable key and the token
  Note over P,G: the person designs, and Lettrove saves as they work
  G-->>P: design:saved { designId, revision }
  G-->>S: webhook design.saved (if you set one up)
  P->>S: (before the token runs out) getToken()
```

## Words we use

The [glossary](/docs/api/glossary) lists every term. The ones that most often get mixed up:

- **Design**, never "template" or "document", for what a person makes. (A *document* is one of the
  four modes.)
- **Environment** (test or live) is about keys. **Mode** (email, page, popup, document) is about
  what the editor makes.
- **End user** is the person in your product. **You** are the customer who holds the project.