Permissions
The API decides each call from the account's bindings (vinculos): a binding is a role with a scope (where it applies). There are no separate "integration" permissions: the account can do exactly what the same person could do in the app.
Scope
Scope is hierarchical: institution ⊃ discipline ⊃ class. A binding applies at its scope and below, never above or beside it. Someone who teaches class A does not see class B.
Roles
| Role | Binding scope | Capabilities |
|---|---|---|
ADMIN_PLATAFORMA | global | PLATAFORMA, ADMINISTRAR, CADASTRAR, LER (not AVALIAR) |
CURADOR | institution | ADMINISTRAR, CADASTRAR, LER |
PRECEPTOR | institution | LER |
COORDENADOR | discipline | CADASTRAR, LER |
PROFESSOR | class | LER |
AUXILIAR | discipline or class | LER |
Two flags on the binding add capabilities: podeAvaliar grants AVALIAR and podeCadastrar grants CADASTRAR. Not even the platform administrator can assess without the podeAvaliar flag.
Capabilities
| Capability | What it allows |
|---|---|
LER | See academic data in scope (disciplines, classes, enrollments, activities, attendance). |
CADASTRAR | Create and edit disciplines, classes, activities and enrollments in scope. Includes the CSV imports of students and activities. |
AVALIAR | Decide attendance and give grades in scope. |
ADMINISTRAR | The institution's users, bindings, parameters and audit. Includes the CSV import of people. Comes only from CURADOR or ADMIN_PLATAFORMA. |
PLATAFORMA | Create institutions and manage the platform. Only ADMIN_PLATAFORMA. |
In each operation of the reference, the Access field says which capability is required and over which path parameter it is evaluated (for example, CADASTRAR over the class in turmaId).
Which role to give the integration account
Give the smallest role that covers what the integration does:
| The integration... | Account with... |
|---|---|
| only reads attendance or lists of one class | PROFESSOR or AUXILIAR in that class (LER) |
| imports students and activities of classes in a discipline | COORDENADOR of the discipline |
| creates disciplines, or imports people with roles (staff) | CURADOR of the institution |
The integration account does not need (and is better off without) AVALIAR: confirming attendance and giving grades belongs to the people in the class.
When permission is missing
403 FORBIDDEN: the account is authenticated, but no binding covers that operation and scope.401 UNAUTHENTICATED: missing, invalid or expired token; see Authentication.
A list (GET /turmas, GET /instituicoes) returns only what the account can see; so two different accounts get different lists from the same route.