← Lumi for institutions GUIDES FOR YOUR TEAM

Set up your AI tutor: start here

The console, the API, the player and webhooks. Then the sandbox and live environments, your keys, and who does what.

Last updated: 18 November 2026

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 consolehttps://platform-staging.sketchmind.aihttps://platform.sketchmind.ai
API addresshttps://staging.sketchmind.ai/v1https://platform.sketchmind.ai/v1
Player addresshttps://embed-lumi-staging.sketchmind.aihttps://embed-lumi.sketchmind.ai
Keys start withsk_sandbox_sk_live_
On your statementNever. 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.
Two sandbox rules

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:

ScopeWhat it allowsRoutes
launchOpen lessonsPOST /v1/launch
learnersRead, change, pause or erase a student/v1/learners/{userId}
libraryUpload lessons and read the library/v1/library, /v1/library/lessons/{slug}, /v1/library/import, /v1/library/batches/{batchId}
usageRead 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

WhoWhat they do
SketchMindCreates 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 developersMake keys, add the launch call to your server, open the player, and run a webhook receiver. See Integration and Webhooks.
Your content teamBuild 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:

  1. Make a sandbox key with the launch scope.
  2. Launch a test student with one call (see Integration) and open the link.
  3. Connect your webhook and send a test message (see Webhooks).
  4. Add a few lessons, watch them and approve them (see Library).
  5. 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 the slug or lessonId.
  • 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.