PARTNERS

API

Last updated: 22 September 2026

Public partner reference for The Globals: school sign-in, shared identity, completion events, Jupas, and school report mail. Application routes under /api/ are not listed here.

OVERVIEW

What this page covers

A public contract for school portals and Macenta products that connect to The Globals. It describes identity, sign-in, shared progress, and school report mail — not private application endpoints.

Product code: the-globals
Audience: School LMS partners, Macenta product teams, and schools adding The Globals without custom product code.
Status: Living reference. Existing school links keep working while the shared Macenta services roll out.

IDENTITY

Who a user is

The Globals maps a school person to one platform account. The school mailbox is stored when provided; sign-in uses the platform address.

username: Stable school username (no domain).
loginHint: Platform sign-in address: {username}@theglobals.co.
orgEmail: Optional real school mailbox. Not used to sign in.
displayName: Given name and family name.
role: student, teacher, school_admin, system_admin, or parent.
orgId / orgName: School or organisation.
campusId / campusName: Campus within the school.
classes[]: Class name, grade (1–12), and content level.
locale: Preferred interface language, for example en or tr.
entitlements[]: Macenta products this person may open.

Roles in The Globals
Role	After sign-in
student	Learner home and units
teacher	Class tools and reports
school_admin	School-wide administration
system_admin	Publisher operations
parent	Linked child progress

SIGN-IN

How a school sends a learner

The school portal redirects the browser to The Globals with a short-lived signed session token. The Globals creates or resumes the matching account. Entitled Macenta products open without signing in again.

Entry URL: https://theglobals.co/?token=<signed-token>

The token payload should identify the person (username, name, role) and their organisation (school, campus, classes). Teachers may belong to more than one class.

POST /v1/auth/exchange — request

{
  "grantType": "lms_token",
  "product": "the-globals",
  "lmsToken": "<signed school session token>"
}

POST /v1/auth/exchange — response

{
  "macentaUserId": "usr_example",
  "launchToken": "<short-lived token>",
  "user": {
    "username": "student123",
    "loginHint": "student123@theglobals.co",
    "orgEmail": "student123@example-school.edu",
    "displayName": "Ada Example",
    "role": "student",
    "orgId": "example-school",
    "orgName": "Example School",
    "campusName": "Main Campus",
    "classes": [{ "name": "7B", "grade": 7, "level": "3" }],
    "locale": "en",
    "entitlements": ["the-globals"]
  }
}

COMPLETIONS

Progress that can be shared

Authorised products may read portable activity. The Globals does not publish writing bodies or donation wallets through this contract.

activity.completed: A unit section is finished (listening, reading, or similar).
quiz.completed: A quiz attempt is submitted, with score and time spent.
speaking.completed: A speaking practice session is finished, with score and duration.
assignment.submitted: Writing or an open task is handed in. Body text is not shared by default.
session.seen: The learner was last active.

Portable data fields

unitId: Unit or course title.
sectionId: Section within the unit.
progressPercent: Completed sections divided by total sections.
score / maxScore: Normalised lesson or quiz score, typically 0–100.
durationSec: Speaking session length.
timeSpentSec: Quiz time on task.
streakDays: Consecutive active days.
lastSeenAt: Most recent activity timestamp (ISO 8601).

POST /v1/events

{
  "product": "the-globals",
  "macentaUserId": "usr_example",
  "type": "activity.completed",
  "occurredAt": "2026-09-22T10:00:00Z",
  "orgId": "example-school",
  "className": "7B",
  "data": {
    "unitId": "Affordable and Clean Energy",
    "sectionId": "Listening",
    "progressPercent": 25,
    "score": 72,
    "maxScore": 100
  }
}

Stays inside The Globals

Jupa wallet balances and Support Others donations
UN Sustainable Development Goal unit catalogues
Digital-impact leaf, sapling, and tree milestones
Ambassador certificates and in-product leaderboards
Writing answer bodies, uploads, and teacher comments

JUPAS

Points in The Globals

Jupas are the in-product currency learners earn from lessons, quizzes, speaking, and teacher marks, and may spend in Support Others.

Partners can consume portable scores and completion percentages. They do not create, spend, or correct Jupa balances. A lesson score on a completion event is a 0–100 result, not a wallet mutation.

School report mail

The Globals sends branded weekly and monthly school reports to a short list of named administrators and publisher liaisons — not to every teacher, and not to parents by default.

Mail is sent as The Globals from noreply@theglobals.co. The product still decides who receives a report and builds the HTML. A shared Macenta mail service only delivers the message.

POST /v1/mail/send

{
  "product": "the-globals",
  "from": { "email": "noreply@theglobals.co", "name": "The Globals" },
  "replyTo": "support@theglobals.co",
  "to": ["head@example-school.edu"],
  "subject": "The Globals | Example School weekly report ready",
  "html": "<!DOCTYPE html>…",
  "tags": {
    "type": "weekly_school_report",
    "weekKey": "2026-W38",
    "school": "Example School"
  }
}

HTTP

Partner reference

Draft Macenta partner paths. They are not this website’s /api/ application routes. Errors return a short code; products map that to a safe message.

Partner HTTP methods and paths
Method	Path	Purpose
POST	/v1/auth/exchange	Exchange a school or product session for a short-lived launch token and profile.
GET	/v1/me	Return the signed-in profile.
GET	/v1/users/{id}	Read a user in the same organisation, when authorised.
POST	/v1/launch	Open another entitled Macenta product without signing in again.
GET	/v1/products	List products this organisation may use.
PUT	/v1/orgs/{orgId}	Register or update a school once. No product-side custom code for a standard school.
POST	/v1/mail/send	Send transactional HTML mail as The Globals.
POST	/v1/events	Publish a portable completion or activity event.
GET	/v1/users/{id}/activity	Read portable activity for an authorised viewer.

POST /v1/launch

{
  "from": "the-globals",
  "to": "speqra",
  "macentaUserId": "usr_example",
  "returnUrl": "https://theglobals.co/student",
  "locale": "en",
  "context": {
    "assignmentId": "unit-energy-speaking",
    "completion": {
      "unitId": "Affordable and Clean Energy",
      "sectionId": "Speaking"
    }
  }
}

PUT /v1/orgs/{orgId}

{
  "displayName": "Example School",
  "products": ["the-globals"],
  "campuses": [{ "id": "main", "name": "Main Campus" }]
}

Error body

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "This request is not allowed."
  }
}

SCHOOLS

Adding a school

Register the organisation once — name, campuses, and entitled products. Learners then arrive from the school portal or from a provisioned roster.

A standard school does not need custom work inside The Globals. For access or a test organisation, write to support@theglobals.co.