Permissions

A valid token proves who you are. It does not decide what you may do. That is decided by the roles on your account, which an operator sets. Every route except GET /v1/health needs a permission, and a request your roles do not cover answers 403 forbidden.

This page explains how to read your roles, how the API matches them against a request, which role grants each operation, and which roles to ask for.

Where to see your roles

GET /v1/api-account/validate-me returns them:

curl -s https://api.main-team.org/v1/api-account/validate-me \
  -H "Authorization: Bearer $TOKEN" | jq .roles

[
  { "effect": "allow", "action": "api/*", "target": "mto" },
  { "effect": "allow", "action": "*/read", "target": "mto" },
  { "effect": "allow", "action": "student/*", "target": "mto" },
  { "effect": "allow", "action": "*/read", "target": "stem" },
  { "effect": "allow", "action": "student/update", "target": "stem" },
  { "effect": "allow", "action": "application/*", "target": "stem" },
  { "effect": "allow", "action": "auth/signin", "target": "stem" },
  { "effect": "disallow", "action": "application/delete", "target": "*" }
]

(validate-me itself needs api/* on mto. If it answers 403, ask for that role first. See Authentication.)

Only an operator can change roles. A change reaches the API within 60 seconds, and it applies to the tokens you already hold, because roles belong to your account, not to the token.

Anatomy of a role

A role has four fields:

effect

allow grants, disallow forbids. A disallow that matches a request always wins over any allow that matches the same request (see Disallow wins).

action

An action is <resource>/<operation>. The API uses these resources and operations:

target

The target says which organization a role covers. Every request acts on exactly one organization:

Consequences worth knowing:

• A role with target stem does nothing on flat routes. Registering students (POST /v1/student) needs a role on mto or *, even if all your work is on stem.
• A role with target mto does nothing on /v1/{stem's id}/....
• A role with target * covers everything, flat routes included. Keep that in mind when you ask for *.
• Because mto is the default target, a role saved without a target covers only the flat routes.

Organizations lists which routes are flat.

authorized

authorized says whose role it is. Leave it empty: an empty authorized means "the account that holds this role", which is always what you want. Setting it to your own account _id means the same thing. A role whose authorized is any other id does nothing at all, neither as an allow nor as a disallow. If you see a role like that in validate-me, it is a mistake to report to the operator.

How a request is checked

For each request, the API knows the action the route needs (see the matrix) and the organization it acts on. It then:

1. collects the matching roles: those whose action grants the needed action, whose target is * or the request's organization, and whose authorized is empty or your own id;
2. refuses if any matching role is a disallow;
3. allows if any matching role is an allow;
4. refuses otherwise. Having no matching role at all is a refusal.

The default is to refuse. A route is never open just because you have a token.

A refusal looks like this:

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient role permissions",
    "documentation_url": "https://hub.main-team.org/api/errors#forbidden",
    "request_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9"
  }
}

403 means your token is valid and your roles do not cover this request. Signing a new token or retrying does not help. Ask for the role.

Wildcards

In a role's action, * stands for "anything" in the segment where it appears, and * on its own grants every action.

Two rules decide every case:

1. The segment counts must agree. A two-part pattern such as student/* matches two-part actions only. Only * alone matches everything.
2. The api routes need api/* literally. validate-me and revoke-token ask for api/*, and a role grants that only if its action is api/*, */* or *. */read does not grant it, because read is not *, and neither does api/read.

Disallow wins

A disallow role that matches a request refuses it, whatever allow roles also match. This makes it easy to grant broadly and carve out exceptions:

A disallow follows the same matching rules as an allow. Its target must match the request's organization, and its authorized must be empty or your own id.

auth/signin is its own namespace

auth/signin grants the two ways of acting as a student in their panel:

Both are stronger than reading or updating a student: they let a browser sign in as that student. That is why no student/* or api/* role implies them, and why an operator has to grant auth/signin explicitly. *, */* and auth/* do include it, so a broad role grants it too, unless you add a disallow.

Registering a student with a password field but without auth/signin on mto is refused before anything is written:

{
  "error": {
    "code": "forbidden",
    "message": "Setting a student's password needs the auth/signin permission on mto, the same grant a sign-in link needs.",
    "documentation_url": "https://hub.main-team.org/api/errors#forbidden",
    "request_id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
  }
}

Registering without a password needs only student/create. See Passwords and Sign-in links.

Other 403 answers

A few routes also answer 403 forbidden for a rule of their own, which has nothing to do with roles. Their message names the rule:

Only Insufficient role permissions means "ask for a role". Base your code on the status and error.code, and show the message to a person. The route-specific 403s are decided after the rate limit, so unlike a role refusal they count against it.

The order of checks

The permission check has a fixed place in the order of checks, which explains some answers that look surprising:

1. Reading the body. A body over 100 kB (413), in an encoding the API does not read (415), or that is not valid JSON (400) is refused first, before the token is looked at.
2. Token. A bad token is 401 on every route.
3. Organization id (per-organization routes). An unknown id is 404 Organization not found!, even if you would have had no permission there.
4. Permission. 403 if your roles do not cover the request.
5. Rate limit. 429. Requests refused at steps 2 to 4 are not counted.
6. Validating the body. 400 for a missing, badly formatted or unknown field. So a request whose JSON is valid but whose fields are wrong, sent without the permission, answers 403, not 400.
7. The route's own rules. For example, a student who is not yours is treated as missing here, after the permission check (see Organizations). Without student/read you get 403 for every student id, yours or not.

Ready-made role profiles

These profiles cover the usual integrations. Copy the one that fits into your request to the operator. In every profile authorized is left empty.

Connectivity only

For monitoring or a first test.

Reference data reader

Countries, grades and organizations, for building registration forms.

(allow */read mto is shorter. It also grants reading your students on the core record.)

Enroll students on one olympiad

Register students, send them to the panel with sign-in links, enter them for exams, move and cancel entries, and collect certificates and reports, all on stem. Replace stem with your olympiad's slug.

As JSON, for an operator:

[
  { "effect": "allow", "action": "api/*", "target": "mto" },
  { "effect": "allow", "action": "*/read", "target": "mto" },
  { "effect": "allow", "action": "student/*", "target": "mto" },
  { "effect": "allow", "action": "*/read", "target": "stem" },
  { "effect": "allow", "action": "student/update", "target": "stem" },
  { "effect": "allow", "action": "application/*", "target": "stem" },
  { "effect": "allow", "action": "auth/signin", "target": "stem" }
]

Adding passwords. If you also set students' passwords, add allow auth/signin on mto. Prefer sign-in links where you can; see Passwords.

Adding an olympiad. Repeat the four stem rows with the other slug.

Enroll students on every olympiad, without passwords

The last row keeps the password routes closed while sign-in links work everywhere.

Follow group challenges

Read where your students stand in an organization's group challenges, and submit their steps and their group's work. Replace stem with your olympiad's slug. Group challenges answer only on organizations where they are switched on.

Leave out the group-challenge/submit row to follow without acting. */read already includes group-challenge/read; */* and * include both.

Results collector (read-only)

A nightly job that reads students, applications, certificates and reports, and changes nothing.

Everything, with guard rails

* grants every action, auth/signin included. Drop the disallow rows only if you really need deletes or passwords.

Least privilege

Ask for the smallest profile that does the job. A leaked secret can do exactly what your roles allow, no more. A read-only job with read-only roles cannot change anything, whatever happens to its credentials. See Security.

Operation permission matrix

Every operation, the action it needs, and the role targets that grant it. Paths use {organizationId} for the organization _id.

On top of the exact action, every action below is also granted by *, by */*, by <resource>/* (for example student/*) and by */<operation> (for example */read), with one exception: api/* is granted only by api/*, */* and *.

Account and health

Reference data

Students on the core record

Students in an organization

Exams

Applications

Certificates and reports

Group challenges

Check your roles in code

To catch a missing role before you make the call, for example to hide a button in your own admin screen, you can apply the same rules to the roles validate-me returns. This mirrors the API's rules. The API's own answer is still the one that counts.

// Does a stored role's action grant the needed action?
function actionGrants(pattern, action) {
  if (!pattern) return false;
  if (pattern === '*' || pattern === action) return true;
  const p = pattern.split('/');
  const a = action.split('/');
  if (p.length !== a.length) return false;
  return p.every((part, i) => part === '*' || part === a[i]);
}

/**
 * account: the object from GET /v1/api-account/validate-me
 * action:  e.g. 'application/create' (see the matrix above)
 * org:     the organization slug the request acts on; 'mto' for flat routes
 */
function canCall(account, action, org) {
  const matching = (account.roles ?? []).filter(
    (role) =>
      actionGrants(role.action, action) &&
      (role.target === '*' || role.target === org) &&
      (!role.authorized || role.authorized === account._id),
  );
  if (matching.some((role) => role.effect === 'disallow')) return false;
  return matching.some((role) => role.effect === 'allow');
}

canCall(account, 'application/create', 'stem'); // true with the enrollment profile
canCall(account, 'auth/signin', 'mto');          // false: no password role

function actionGrants(?string $pattern, string $action): bool
{
    if ($pattern === null || $pattern === '') return false;
    if ($pattern === '*' || $pattern === $action) return true;
    $p = explode('/', $pattern);
    $a = explode('/', $action);
    if (count($p) !== count($a)) return false;
    foreach ($p as $i => $part) {
        if ($part !== '*' && $part !== $a[$i]) return false;
    }
    return true;
}

function canCall(array $account, string $action, string $org): bool
{
    $matching = array_filter($account['roles'] ?? [], fn ($role) =>
        actionGrants($role['action'] ?? null, $action)
        && (($role['target'] ?? null) === '*' || ($role['target'] ?? null) === $org)
        && (empty($role['authorized']) || $role['authorized'] === $account['_id']));

    foreach ($matching as $role) {
        if (($role['effect'] ?? null) === 'disallow') return false;
    }
    foreach ($matching as $role) {
        if (($role['effect'] ?? null) === 'allow') return true;
    }
    return false;
}

Roles can change at any time (within 60 seconds of an operator's edit), so refresh your copy of validate-me now and then rather than keeping it forever.

Asking for a role

Write to info@main-team.org from your registered contact address with:

• your apiKey (never the secret),
• the operations you need, by name from the matrix, or a profile from this page,
• the organizations, by slug,
• for a 403 you already hit: the request_id, the time in UTC and the request you made.

A granted role works within 60 seconds, with the token you already have.