Users and bindings
An institution's people and roles: creation, invitation and bindings.
List the institution's people
GET /instituicoes/{instituicaoId}/usuarios
Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Success status: 200.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
instituicaoId | string (uuid) | yes | Institution id. |
Query parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
busca | string | no | to 100 characters | Search text (name or email, depending on the route). |
limite | integer | no | 1…200; default: 50 | How many items per page (1 to 200; the default varies by route, usually 50). |
deslocamento | integer | no | 0…100000; default: 0 | How many items to skip, for paging (up to 100000). |
inativos | "true" | "false" | no | default: "false" | true also includes inactive records. |
tipo | "equipe" | "alunos" | no | Filter by type. | |
papel | "CURADOR" | "PRECEPTOR" | "COORDENADOR" | "PROFESSOR" | "AUXILIAR" | "ALUNO" | no | Filter by role (e.g. PROFESSOR). | |
status | "CONVIDADO" | "ATIVO" | "SUSPENSO" | no | Filter by status. |
Response
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
items | list of UsuarioDto | yes | ||
total | integer | yes | 0… | |
contagens | UsuarioContagens | no |
On error: ErroApi model.
Example
curl -X GET "$API/instituicoes/{instituicaoId}/usuarios" -H "Authorization: Bearer $TOKEN"Create a staff member and bind them
POST /instituicoes/{instituicaoId}/usuarios
Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Rate limit: up to 120 calls every 60 s per origin. Success status: 201.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
instituicaoId | string (uuid) | yes | Institution id. |
Request body (EquipeCriar)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
email | yes | |||
nome | string | yes | 1–200 characters | |
nationality | string or null | no | 2–2 characters; ^[A-Za-z]{2}$ | |
locale | "pt-BR" | "es" | "en-US" or null | no | ||
papel | "CURADOR" | "PRECEPTOR" | "COORDENADOR" | "PROFESSOR" | "AUXILIAR" | yes | ||
disciplinaId | string (uuid) or null | no | ||
turmaId | string (uuid) or null | no | ||
podeAvaliar | boolean | no | default: false | |
podeCadastrar | boolean | no | default: false |
Response
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
id | string (uuid) | yes | ||
email | string | yes | ||
nome | string | yes | ||
status | "CONVIDADO" | "ATIVO" | "SUSPENSO" | yes | ||
nationality | string or null | yes | ||
locale | "pt-BR" | "es" | "en-US" or null | yes | ||
compartilhado | boolean | yes | Has a binding or enrollment at another institution: only the platform changes name and status. | |
jaExistia | boolean | no | Only in the create response: the email already had an account and the person was bound to it. |
On error: ErroApi model.
Example
curl -X POST "$API/instituicoes/{instituicaoId}/usuarios" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"email":"texto","nome":"texto","papel":"CURADOR"}'Read a person of the institution
GET /instituicoes/{instituicaoId}/usuarios/{usuarioId}
Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Success status: 200.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
usuarioId | string (uuid) | yes | Person id. | |
instituicaoId | string (uuid) | yes | Institution id. |
Response
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
id | string (uuid) | yes | ||
email | string | yes | ||
nome | string | yes | ||
status | "CONVIDADO" | "ATIVO" | "SUSPENSO" | yes | ||
nationality | string or null | yes | ||
locale | "pt-BR" | "es" | "en-US" or null | yes | ||
compartilhado | boolean | yes | Has a binding or enrollment at another institution: only the platform changes name and status. | |
jaExistia | boolean | no | Only in the create response: the email already had an account and the person was bound to it. |
On error: ErroApi model.
Example
curl -X GET "$API/instituicoes/{instituicaoId}/usuarios/{usuarioId}" -H "Authorization: Bearer $TOKEN"Update a person of the institution
PATCH /instituicoes/{instituicaoId}/usuarios/{usuarioId}
Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Success status: 200.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
usuarioId | string (uuid) | yes | Person id. | |
instituicaoId | string (uuid) | yes | Institution id. |
Request body (UsuarioAtualizar)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
nome | string | no | 1–200 characters | |
nationality | string or null | no | 2–2 characters; ^[A-Za-z]{2}$ | |
locale | "pt-BR" | "es" | "en-US" or null | no | ||
status | "ATIVO" | "SUSPENSO" | no |
Response
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
id | string (uuid) | yes | ||
email | string | yes | ||
nome | string | yes | ||
status | "CONVIDADO" | "ATIVO" | "SUSPENSO" | yes | ||
nationality | string or null | yes | ||
locale | "pt-BR" | "es" | "en-US" or null | yes | ||
compartilhado | boolean | yes | Has a binding or enrollment at another institution: only the platform changes name and status. | |
jaExistia | boolean | no | Only in the create response: the email already had an account and the person was bound to it. |
On error: ErroApi model.
Example
curl -X PATCH "$API/instituicoes/{instituicaoId}/usuarios/{usuarioId}" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'Resend the invitation email
POST /instituicoes/{instituicaoId}/usuarios/{usuarioId}/convite
Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Rate limit: up to 30 calls every 60 s per origin. Success status: 204.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
usuarioId | string (uuid) | yes | Person id. | |
instituicaoId | string (uuid) | yes | Institution id. |
Response
No response body.
On error: ErroApi model.
Example
curl -X POST "$API/instituicoes/{instituicaoId}/usuarios/{usuarioId}/convite" -H "Authorization: Bearer $TOKEN"List the institution's bindings
GET /instituicoes/{instituicaoId}/vinculos
Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Success status: 200.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
instituicaoId | string (uuid) | yes | Institution id. |
Query parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
busca | string | no | to 100 characters | Search text (name or email, depending on the route). |
limite | integer | no | 1…200; default: 50 | How many items per page (1 to 200; the default varies by route, usually 50). |
deslocamento | integer | no | 0…100000; default: 0 | How many items to skip, for paging (up to 100000). |
inativos | "true" | "false" | no | default: "false" | true also includes inactive records. |
usuarioId | string (uuid) | no | Person id. |
Response
list of VinculoItem (+ total)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
id | string (uuid) | yes | ||
usuarioId | string (uuid) | yes | ||
nome | string | yes | ||
email | string | yes | ||
papel | "ADMIN_PLATAFORMA" | "CURADOR" | "PRECEPTOR" | "COORDENADOR" | "PROFESSOR" | "AUXILIAR" | yes | ||
instituicaoId | string (uuid) or null | yes | ||
disciplinaId | string (uuid) or null | yes | ||
turmaId | string (uuid) or null | yes | ||
podeAvaliar | boolean | yes | ||
podeCadastrar | boolean | yes | ||
ativo | boolean | yes |
On error: ErroApi model.
Example
curl -X GET "$API/instituicoes/{instituicaoId}/vinculos" -H "Authorization: Bearer $TOKEN"Create a binding (role and scope) for a person
POST /instituicoes/{instituicaoId}/vinculos
Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Rate limit: up to 120 calls every 60 s per origin. Success status: 201.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
instituicaoId | string (uuid) | yes | Institution id. |
Request body (VinculoCriar)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
usuarioId | string (uuid) | yes | ||
papel | "CURADOR" | "PRECEPTOR" | "COORDENADOR" | "PROFESSOR" | "AUXILIAR" | yes | ||
disciplinaId | string (uuid) or null | no | ||
turmaId | string (uuid) or null | no | ||
podeAvaliar | boolean | no | default: false | |
podeCadastrar | boolean | no | default: false |
Response
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
id | string (uuid) | yes | ||
usuarioId | string (uuid) | yes | ||
nome | string | yes | ||
email | string | yes | ||
papel | "ADMIN_PLATAFORMA" | "CURADOR" | "PRECEPTOR" | "COORDENADOR" | "PROFESSOR" | "AUXILIAR" | yes | ||
instituicaoId | string (uuid) or null | yes | ||
disciplinaId | string (uuid) or null | yes | ||
turmaId | string (uuid) or null | yes | ||
podeAvaliar | boolean | yes | ||
podeCadastrar | boolean | yes | ||
ativo | boolean | yes |
On error: ErroApi model.
Example
curl -X POST "$API/instituicoes/{instituicaoId}/vinculos" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"usuarioId":"0198a000-0000-7000-8000-000000000001","papel":"CURADOR"}'Update a binding
PATCH /instituicoes/{instituicaoId}/vinculos/{vinculoId}
Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Success status: 200.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
vinculoId | string (uuid) | yes | Binding id. | |
instituicaoId | string (uuid) | yes | Institution id. |
Request body (VinculoAtualizar)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
podeAvaliar | boolean | no | ||
podeCadastrar | boolean | no | ||
ativo | boolean | no |
Response
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
id | string (uuid) | yes | ||
usuarioId | string (uuid) | yes | ||
nome | string | yes | ||
email | string | yes | ||
papel | "ADMIN_PLATAFORMA" | "CURADOR" | "PRECEPTOR" | "COORDENADOR" | "PROFESSOR" | "AUXILIAR" | yes | ||
instituicaoId | string (uuid) or null | yes | ||
disciplinaId | string (uuid) or null | yes | ||
turmaId | string (uuid) or null | yes | ||
podeAvaliar | boolean | yes | ||
podeCadastrar | boolean | yes | ||
ativo | boolean | yes |
On error: ErroApi model.
Example
curl -X PATCH "$API/instituicoes/{instituicaoId}/vinculos/{vinculoId}" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'