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 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) |
| For | Building and testing | Your real users |
Build with test keys; switch to live keys when you launch. Test and live keys has the checklist.
How a session goes
Words we use
The 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.