These guides are for the people who set Lumi up inside your institution: your developers, your content team and whoever runs the partner console. Start here, then read the guide for your part of the work.
The pieces
- The partner console is the website where your team works: keys, your library, reviews, students, plans, statements and your tutor’s name and look.
- The partner API is what your server calls. Its main job is to ask for a launch link: a one-time address that opens one lesson for one student.
- The player is the page that link opens. It shows the board, speaks the lesson and answers the student’s questions. You open it in your app, on your website or in a new tab.
- Webhooks are messages our server sends to yours when something happens, for example when a student finishes a lesson.
Your students never sign in to Lumi. Your server names each student with your own id, and the player opens straight into the lesson.
Two environments
You get two separate copies of your organisation. Test everything in the sandbox first, then repeat the same steps in live.
| Sandbox (testing) | Live (your real students) | |
|---|---|---|
| Partner console | https://platform-staging.sketchmind.ai | https://platform.sketchmind.ai |
| API address | https://staging.sketchmind.ai/v1 | https://platform.sketchmind.ai/v1 |
| Player address | https://embed-lumi-staging.sketchmind.ai | https://embed-lumi.sketchmind.ai |
| Keys start with | sk_sandbox_ | sk_live_ |
| On your statement | Never. Sandbox lessons are counted apart and not billed. | Yes |
What keeps them apart:
- Separate sign-ins. Each console has its own accounts and its own team. Being a member of one does not give access to the other.
- Separate keys. The sandbox console makes sandbox keys; the live console makes live keys. A sandbox key sent to the live address is refused with
sandbox_key_not_accepted. - Separate students and libraries. A student, a lesson or a launch link from one environment is unknown in the other. Upload your library file in each.
- Webhooks fire in both. Sandbox lessons send real webhook messages, so you can test your receiver end to end before you go live.
Requests to the sandbox address must carry a User-Agent header (curl and every common HTTP library send one), and a request body must not contain the word localhost. Either one is refused with a 403 before it reaches the API. The live address has no such rule.
Keys and what they can do
An API key is the secret your server sends with every call, as Authorization: Bearer <key>. Keep it on your server: never put it in a web page, an app or a launch link.
- Make one on the console’s Integration page, under API keys. Pick what it may do (its scopes) and give it a label.
- The full key is shown once, when you make it. Afterwards the console shows only its last four characters, as “ending a9Qz”. If you lose it, replace it.
- Replace (rotate) makes a new key with the same scopes. The old key keeps working for 24 hours, so you can switch without a gap, then stops with
api_key_revoked. - Turn off stops a key at once. Use it for a key that leaked.
- Each environment holds at most 10 working keys.
A key’s scopes say which calls it may make:
| Scope | What it allows | Routes |
|---|---|---|
launch | Open lessons | POST /v1/launch |
learners | Read, change, pause or erase a student | /v1/learners/{userId} |
library | Upload lessons and read the library | /v1/library, /v1/library/lessons/{slug}, /v1/library/import, /v1/library/batches/{batchId} |
usage | Read numbers: the statement, lesson results, coverage, a student’s progress | /v1/usage, /v1/analytics/lessons, /v1/library/coverage, /v1/learners/{userId}/progress |
A call outside a key’s scopes is refused with insufficient_scope, and the answer names the scope it needed. A key that only launches lessons is the safest key to keep on the server that students’ requests reach.
Who does what
| Who | What they do |
|---|---|
| SketchMind | Creates your organisation and seats your first owner. Sets up your plans with you and adds or removes plans. Switches your websites on for the player to show in a frame. Turns on your own material (PDFs and notes). |
| Owner (console) | Everything in the console, including the Team page: adding teammates and choosing their roles. |
| Admin (console) | Everything except the Team page: keys, webhook, websites, library, reviews, students, plans and brand. |
| Reviewer (console) | Works in the Library: watches, approves, rejects and takes off recordings. |
| Analyst (console) | Sees Overview, Students, Library, Statements and Plans, and changes nothing. |
| Your developers | Make keys, add the launch call to your server, open the player, and run a webhook receiver. See Integration and Webhooks. |
| Your content team | Build the library, add your material and review every recording before students see it. See Library and Sources. |
To add a teammate, an owner opens Team and adds them by email or by their Account ID. The person needs a SketchMind account with a verified email first. A teammate is never deleted: removing one sets them to No access, and their past actions stay in Activity.
The order to set up in
The console’s Overview page keeps a Get set up checklist. In the sandbox console:
- Make a sandbox key with the
launchscope. - Launch a test student with one call (see Integration) and open the link.
- Connect your webhook and send a test message (see Webhooks).
- Add a few lessons, watch them and approve them (see Library).
- Name your tutor on Brand & tutor, and add your team.
Then do the same in the live console with a live key.
Words used in these guides
- Student: one of your learners, known to us only by your id for them (
userId). We never ask for a name, phone or email. - Plan: the rules for a group of students, such as how many lessons they may start each day. In the API a plan is called an
entitlement. See Students and plans. - Lesson: what a student opens. A library lesson is one you prepared and approved; an Ask lesson is made on the spot from the student’s own question or topic.
- Lesson ID: your short name for a library lesson, like
concave-mirror-images. In the API it is theslugorlessonId. - Recording: one prepared version of a library lesson, in one language, depth, difficulty and (optionally) delivery. Only an approved recording reaches students.
- Question: something a student asks during a lesson. The API calls these
doubts. - Statement: the monthly count of your students’ lessons, in the unit your agreement names. Counts only, never money.