# Glossary > The words this documentation uses, each defined once, with a link to the page that explains it in full. Each term is defined once, in the sense this documentation uses it. The link after a definition goes to the page that covers the topic in full. Terms are grouped by topic and sorted alphabetically within each group. ## Access and authentication ### Action The first part of a [role](#role): what the role lets you do, written `/`, for example `student/read` or `application/create`. A `*` in either segment matches any value there (`student/*`, `*/read`, `*/*`). A `*` on its own matches every action. The two sides must have the same number of segments. For example, `student/*` grants `student/read` but not a deeper action. See [Permissions](https://hub.main-team.org/api/permissions). ### Allow and disallow The `effect` of a [role](#role). An account needs a matching `allow` role for a request to go through. A matching `disallow` role always wins over any number of matching `allow` roles, so it is how you carve an exception out of a broad grant, for example "everything except deleting applications". ### API account The identity your integration uses to call the API. An operator creates it and gives you its [apiKey](#apikey) and [apiSecret](#apisecret). Everything you create through the API belongs to this account, including students and applications. Another account, even a replacement account for the same company, cannot see those records. See [Authentication](https://hub.main-team.org/api/authentication). ### apiKey The public identifier of your [API account](#api-account): `key_` followed by 24 letters, digits, `-` or `_`. You put it in the `kid` header of every [token](#token) and again as the token's `sub` claim. It is not a secret, but it is useless without the matching [apiSecret](#apisecret). ### apiSecret Your signing key: `secret_` followed by a long random string. You get it once, when the account is created, and it cannot be recovered or shown again. It signs your [tokens](#token) and must never leave your servers. See [Security](https://hub.main-team.org/api/security). ### authorized The third part of a [role](#role). If it is empty or holds your own account's `_id`, the role applies to your account. If it holds any other id, the role does nothing, and this is true for `disallow` roles too. ### Clock skew How far your server's clock may disagree with the API's clock: **30 seconds**. The API still accepts a token for 30 seconds after its `exp`. It also accepts an `iat` up to 30 seconds in the future, but no further. ### iat and exp The two required time claims of a [token](#token), in whole seconds since the Unix epoch. `iat` is when you signed the token and `exp` is when it stops working. `exp` must be later than `iat`, and `exp - iat` may be at most **3600** seconds. ### kid The JWT header field that names the key a token was signed with. For this API it is always your [apiKey](#apikey). The API reads it to decide which account's secret to check the signature against. ### Operator A Main Team staff member who manages API accounts. Operators create accounts, set their [roles](#role), and deactivate them. You cannot do any of this yourself through the API. Write to [support](https://hub.main-team.org/api/support) to ask. ### Permission What a single operation requires: an [action](#action) on the [organization](#organization) the request acts on. For example, `POST /v1/{organizationId}/application` requires `application/create` on that organization. Each operation's reference page names its permission. See [Permissions](https://hub.main-team.org/api/permissions). ### Revocation Ending one [token](#token) before its `exp`, with [`POST /v1/api-account/revoke-token`](https://hub.main-team.org/api/reference/revoke-token). The API refuses the revoked token from then on. Your other tokens and your apiSecret keep working. ### Role One entry in your account's list of grants: `{ effect, action, target, authorized }`. Operators set roles. You can read yours with [`GET /v1/api-account/validate-me`](https://hub.main-team.org/api/reference/get-current-api-account). See [Permissions](https://hub.main-team.org/api/permissions). ### Target The second part of a [role](#role): which organization the role applies to. It is either `*` (every organization) or one [slug](#slug): `mto`, `stem`, `hilingua`, `neo`, `gmath` or `coding`. Operations without an organization in their path act on `mto`, so they need a role whose target is `mto` or `*`. ### Token The credential you send with every request, as `Authorization: Bearer `. It is a JWT that you sign yourself with HS256 and your [apiSecret](#apisecret). The API has no endpoint that issues tokens. See [Authentication](https://hub.main-team.org/api/authentication) and [Token handling](https://hub.main-team.org/api/tutorials/token-handling). ## Organizations and students ### Activated organizations The organizations a student may be used on, stored on the student as `activatedPlatformsThisSeason`. The value `common` means every organization, and it is the default at registration. Otherwise the list holds organization [slugs](#slug). A student must be activated for an organization before you can create a [sign-in link](#sign-in-link) there, and before they appear in that organization's student list. See [Students](https://hub.main-team.org/api/guides/students). ### Bulk registration Registering 30 to 1000 students in one request with [createStudentImport](https://hub.main-team.org/api/reference/create-student-import). The batch is checked before it is accepted and then registered in the background, all of it or none of it. See [Bulk registration](https://hub.main-team.org/api/guides/bulk-registration). ### Core record The main copy of a student, which Main Team keeps under the `mto` organization. Registration creates it. It holds the profile, the username and the password. The operations without an organization in their path act on the core record. Its `_id` is the student id you use everywhere in this API. See [Organizations](https://hub.main-team.org/api/organizations). ### Email confirmation Whether the student has proven they receive email at their address, returned as `emailConfirmed`. Students you register start out unconfirmed. Changing a student's email address through the API resets it to `false`. It does not stop a [sign-in link](#sign-in-link) from working, but the panel asks an unconfirmed student to confirm their address with an emailed 6-digit code, on every page until they do, My Exams included, so they must confirm before starting an exam. A student already inside an exam room is not interrupted. Only the confirmation on the [core record](#core-record) counts. Once it is `true`, you can no longer set the student's password. ### Import One batch sent to [createStudentImport](https://hub.main-team.org/api/reference/create-student-import), and the record of what happened to it. Read it with [getStudentImport](https://hub.main-team.org/api/reference/get-student-import): `status` runs from `queued` through `running` to `succeeded` or `failed`, every row carries its student's `_id` once it has succeeded, and the import stops being readable 30 days after it finishes. ### Flat operation An operation whose path has no `{organizationId}`, such as `GET /v1/student` or `GET /v1/country`. It acts on the [core record](#core-record), and its permission is checked against the `mto` target. ### mainId The core-record id of a person, carried on every person that an organization's data returns. Each organization keeps its own copy of a student with a different `_id`, so the `user._id` on an application is that organization's id for the student. `mainId` is the id you registered them with, so match your records on `mainId`. See [Identifiers](https://hub.main-team.org/api/identifiers). ### Organization One of the platforms a student can take part in. `mto` is the core platform, and the [flat operations](#flat-operation) act on it. `stem`, `hilingua`, `neo`, `gmath` and `coding` are the olympiads, and you address each one by its [organization id](#organization-id). [`GET /v1/organization`](https://hub.main-team.org/api/reference/list-organizations) lists the organizations you can put in a path. See [Organizations](https://hub.main-team.org/api/organizations). ### Organization copy An organization's own record of a student, linked to the [core record](#core-record) by [mainId](#mainid). It is created the first time the student opens a [sign-in link](#sign-in-link) for that organization, and the API cannot create it any other way. You need it before you can create applications, list a student's applications, certificates or reports, or link a supervisor on that organization. ### Organization id The `_id` of an organization, as returned by [`GET /v1/organization`](https://hub.main-team.org/api/reference/list-organizations): 24 hexadecimal characters. It is the `{organizationId}` in a path. It is never the slug. An id that names no organization, or names one that `GET /v1/organization` does not list, answers `404` with the message `Organization not found!`. ### Ownership The rule that your account can only act on students it registered itself, and on records reached through those students, such as applications, certificates and reports. Another account's record answers exactly like a missing one: `404 not_found`. This means a response never reveals that someone else's record exists. ### Slug The short, lower-case name of an organization: `mto`, `stem`, `hilingua`, `neo`, `gmath` or `coding`. Slugs appear in role targets, where `mto` is one of them, in `activatedPlatformsThisSeason`, which takes the other five and `common`, and in some messages. Paths never take a slug. They take the [organization id](#organization-id). ### Supervisor A teacher or coordinator account on one organization. You link a student to a supervisor by the supervisor's username with [`PUT /v1/{organizationId}/student/{studentId}/supervisor`](https://hub.main-team.org/api/reference/link-student-supervisor). The link applies to that organization only. The API never creates supervisor accounts. See [Supervisors](https://hub.main-team.org/api/guides/supervisors). ### Username The student's platform login name, issued at registration and never changed through the API. It is the country's two-letter code, one letter (never `P`, `S` or `T`), and a sequence number that starts at 1000, for example `XXB1045` with the country's code in place of `XX`. It is not a secret, so a password may not contain it. ## Exams and applications ### Application A student's entry for one [exam](#exam) on one organization. You create one with [`POST /v1/{organizationId}/application`](https://hub.main-team.org/api/reference/create-application), giving the student and the exam. Every application has a [payment](#payment). See [Applications](https://hub.main-team.org/api/guides/applications). ### Available exams The exams one student may apply for on one organization, returned by [`GET /v1/{organizationId}/exam/available/{studentId}`](https://hub.main-team.org/api/reference/list-available-exams) as a tree: category, then session, then language. Each leaf carries the exam as `matchedExam`. The student's grade and country narrow the list, and so do the sittings the student already holds. It follows the same rules as the exam picker in the student panel, and it works before the student has ever signed in to the organization. See [Exams](https://hub.main-team.org/api/guides/exams). ### Exam One paper: a category, sat in one language, at one [session](#session). Its `_id` is what you put in `examId`. ### Exam category A subject or competition line within an organization, for example Science or AI Challenge. Exams belong to one category. An exam in an inactive category is never [open](#open-exam). ### Grade The school year a student is in, stored on the student and required at registration. Every exam accepts a fixed set of grades, so a student is offered only exams for their grade. Grade ids are the same on every organization. See [Reference data](https://hub.main-team.org/api/guides/reference-data). ### matchedExam The exam at a leaf of the [available exams](#available-exams) tree. `matchedExam._id` is the `examId` you send to create or move an application. ### Move Changing which exam an application is for, with [`PUT /v1/{organizationId}/application/{applicationId}`](https://hub.main-team.org/api/reference/move-application). Moves are how you change an application's language or date. They are refused once the exam has started, when the student could not apply for the new exam, and in a few other cases, such as a paid application moving to an exam with a different price. See [Change an application](https://hub.main-team.org/api/tutorials/change-an-application). ### Open exam An exam that is still accepting applications. Its session date is in the future, its category is active, and applications to it are not switched off. Only open exams are listed by [`GET /v1/{organizationId}/exam`](https://hub.main-team.org/api/reference/list-exams) or can be applied for. ### Payment The record of what an application costs and whether it has been paid, returned inside the application. The API creates it with the application, but it never charges or refunds anyone. An exam with no price, or a price of `0`, gets a payment with `amount` `0` and `status` `paid`. ### Session One date on which exams are sat, also called a sitting. A student cannot hold two exams in the same category on the same session. ### Settled payment A payment with `status` `paid` **and** an `amount` above `0`, meaning money has actually been paid. A free exam's payment is not settled, even though its status is `paid`. An application with a settled payment cannot be deleted, and it can be moved only to an exam with the same price. ## Sign-in ### Sign-in link A URL that signs one of your students into one organization's student panel when their browser opens it. It is valid for **120 seconds** and works **once**. You create it with [`POST /v1/{organizationId}/auth/signin`](https://hub.main-team.org/api/reference/create-signin-link) and redirect the browser to it at once. See [Sign-in links](https://hub.main-team.org/api/guides/sign-in-links). ### Redirect The optional path inside the organization where the student lands after signing in, for example `/dashboard`. It must start with a single `/` (so `//` is refused) and contain no whitespace and no backslashes. The text `{userId}` in it is replaced with the student's id on that organization. Without it, the student lands on the organization's home page. ## Results ### Certificate A PDF certificate that an organization issues to a student, for example for taking part or for an award. You list a student's certificates, then download each one. See [Certificates and reports](https://hub.main-team.org/api/guides/certificates-and-reports). ### Released document A certificate or report that the organization has published. Only released documents are listed or downloaded. A document that is not released yet, not yours, or has no file answers the same `404`. ### Report A PDF results report for one of a student's applications. It is listed and downloaded like a certificate. A report that was withdrawn is treated as not released. ### shortId A short identifier that certificates and reports carry in their `shortId` field, next to their `_id`. The download operations accept either one. ## Group challenges ### Grade group A set of grades that form groups together in a group challenge. Every member of a group comes from the same grade group, and a student whose grade is in none of a challenge's grade groups cannot take part. See [Group challenges](https://hub.main-team.org/api/guides/group-challenges#the-challenges). ### Group A handful of students, formed by their teacher in the panel, who work through a group challenge together. It is prepared (`awaiting_payment`, `draft`), confirmed by the teacher (`finalized`), and `completed` once its work is sent. See [Group challenges](https://hub.main-team.org/api/guides/group-challenges#groups). ### Group challenge A project an organization runs for groups of students between two dates (`windowStart` to `windowEnd`), worked through in steps. You can read where your students stand and submit steps for them. See [Group challenges](https://hub.main-team.org/api/guides/group-challenges). ### Step One stage of a group challenge, such as a proposal or a video. A group's steps open one after another: a step is `locked` until the one before it is submitted, `open` while the group uploads work for it, and `submitted` once sent. See [Group challenges](https://hub.main-team.org/api/guides/group-challenges#groups). ## Requests and responses ### documentation_url The link, included in every error, to the explanation of its [error code](#error-code) on the [Errors](https://hub.main-team.org/api/errors) page. ### Envelope The fixed shape every JSON response takes. On success it is `{ success, message, data, pagination? }`. On failure it is `{ error: { code, message, documentation_url, request_id } }`. One operation, [`GET /v1/api-account/validate-me`](https://hub.main-team.org/api/reference/get-current-api-account), returns its object without the success envelope. See [Requests and responses](https://hub.main-team.org/api/requests-and-responses). ### Error code The stable, machine-readable name of an error, such as `unauthorized` or `conflict`, in `error.code`. Your code should branch on the HTTP status and this code, never on the message text. See [Errors](https://hub.main-team.org/api/errors). ### Idempotent An operation you can safely repeat because doing it twice has the same effect as doing it once. Creating an application for the same student and exam twice returns the existing application. Registering a student twice does not: the second attempt is refused. See [Retries and idempotency](https://hub.main-team.org/api/retries-and-idempotency). ### operationId The stable name of an operation in the reference, such as `createApplication`. Its page is at `/api/reference/` followed by the name in kebab case (`/api/reference/create-application`). Quote it when you ask for help. ### Pagination How list operations return their results one page at a time. You choose the page with `page` (default 1) and `limit` (default 20, at most 100), and the response carries `pagination: { page, limit, total, totalPages }`. See [Pagination](https://hub.main-team.org/api/pagination). ### Rate limit How many requests your account may make: **100 requests per 60 seconds to each operation**, and each operation is counted on its own. Past that, the API answers `429` with a `Retry-After` header. See [Rate limits](https://hub.main-team.org/api/rate-limits). ### Request id The id of one request. It comes back in the `X-Request-Id` header of every response and as `error.request_id` in every error. You may send your own id in `X-Request-Id`: up to 256 letters, digits and `. _ : ; = + / @ -`. Any other value is replaced with an id the API generates. Quote the request id when you contact [support](https://hub.main-team.org/api/support). It is how a single request is found in our logs.