Scopes (permissões)

Cada API key possui uma lista de scopes que determinam quais endpoints ela pode acessar. Scopes são granulares por recurso e ação.

Formato

Os scopes seguem o padrão <recurso>:<ação>:

Ação	Significado
`read`	Listar e detalhar (GET)
`write`	Criar, atualizar e excluir (POST, PUT, PATCH, DELETE)
`export`	Exportação de dados (específico para CSV facial)

Scopes disponíveis

Scope	Endpoints permitidos
`series:read`	`GET /v1/series`, `GET /v1/series/:id`
`series:write`	`POST /v1/series`, `PUT /v1/series/:id`, `DELETE /v1/series/:id`, `POST /v1/series/:id/reactivate`
`classes:read`	`GET /v1/classes`, `GET /v1/classes/:id`
`classes:write`	`POST /v1/classes`, `PUT /v1/classes/:id`, `DELETE /v1/classes/:id`, `POST /v1/classes/:id/reactivate`
`disciplines:read`	`GET /v1/disciplines`, `GET /v1/disciplines/:id`, `GET /v1/disciplines/:id/topics`, `GET /v1/disciplines/:id/teachers`
`disciplines:write`	`POST /v1/disciplines`, `PUT /v1/disciplines/:id`, `DELETE /v1/disciplines/:id`, `POST /v1/disciplines/:id/reactivate`, `POST/PUT/DELETE /v1/disciplines/:id/topics[/:topicId]`, `POST/DELETE /v1/disciplines/:id/teachers`
`students:read`	`GET /v1/students`, `GET /v1/students/:id`, `GET /v1/students/:id/gallery`
`students:write`	`POST /v1/students`, `PUT /v1/students/:id`, `DELETE /v1/students/:id`, `POST /v1/students/:id/reactivate`, `DELETE /v1/students/:id/guardian`, `POST/DELETE /v1/students/:id/gallery`, `POST /v1/students/:id/access-block`, `PATCH /v1/students/:id/access-window`, `POST /v1/students/:id/access-sync`
`schoolYears:read`	`GET /v1/school-years`, `GET /v1/school-years/active`, `GET /v1/school-years/:id`
`schoolYears:write`	`POST /v1/school-years`, `PUT /v1/school-years/:id`, `POST /v1/school-years/:id/activate`, `POST /v1/school-years/:id/deactivate`
`students:export`	`GET /v1/students/facial-export`
`frequency:read`	`GET /v1/students/frequency`, `GET /v1/students/:id/frequency`
`reports:read`	`GET /v1/reports/most-absences`, `GET /v1/reports/most-late`, `GET /v1/reports/most-early-exits`
`presences:read`	`GET /v1/user-presences`
`presences:write`	`POST /v1/user-presences`
`equipment:read`	`GET /v1/equipments`, `GET /v1/equipments/:id`, `GET /v1/equipments/:id/mappings/search`, `GET /v1/equipments/:id/sync-status`, `GET /v1/equipments/:id/push-queue`
`equipment:write`	`POST /v1/equipments`, `PUT /v1/equipments/:id`, `DELETE /v1/equipments/:id`, `POST /v1/equipments/intelbras/test-connection`, `POST /v1/equipments/:id/sync-users`, `POST /v1/equipments/:id/access-sync`, `POST /v1/equipments/:id/regenerate-token`
`users:read`	`GET /v1/users`, `GET /v1/users/:id`, `GET /v1/users/:id/work-schedules`, `GET /v1/users/:id/disciplines`
`users:write`	`POST /v1/users`, `PUT /v1/users/:id`, `DELETE /v1/users/:id`, `POST /v1/users/:id/reactivate`, `PUT /v1/users/:id/branches`, `PUT /v1/users/:id/access-roles`, `PUT /v1/users/:id/work-schedules`, `PUT /v1/users/:id/disciplines`, `POST /v1/users/:id/reset-password`, `POST /v1/users/:id/access-block`, `POST /v1/users/:id/access-sync`
`webhooks:read`	`GET /v1/webhooks`, `GET /v1/webhooks/:id`, `GET /v1/webhooks/:id/deliveries`
`webhooks:write`	`POST /v1/webhooks`, `PUT /v1/webhooks/:id`, `DELETE /v1/webhooks/:id`, `POST /v1/webhooks/:id/test`

Exemplo prático

Uma key com scopes ["students:read", "series:read"] pode listar estudantes e séries, mas não pode criar, editar ou exportar.

# ✅ Permite (students:read)
curl https://api.gdredu.com/v1/students \
  -H "Authorization: Bearer gdredu_live_..."

# ❌ Rejeita 403 INSUFFICIENT_SCOPE (students:write)
curl -X POST https://api.gdredu.com/v1/students \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Novo Estudante"}'

Resposta de scope insuficiente:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Scope insuficiente. Necessário: \"students:write\". Scopes da key: [students:read, series:read]."
  }
}

Boas práticas

Princípio do menor privilégio: dê apenas os scopes necessários para a integração.
Keys read-only: para dashboards e relatórios, use apenas scopes *:read.
Keys por integração: não compartilhe uma key com todos os scopes entre múltiplas integrações. Crie uma key por finalidade.
Separação de ambientes: use keys diferentes para homologação e produção.