Skip to main content
Cada token lleva una lista explícita de scopes. El endpoint declara cuál exige; si no está, responde 403 SCOPE_REQUIRED sin mirar nada más.

​
Catálogo v1

El catálogo vive en el propio OpenAPI, bajo la extensión x-edtools-scopeCatalog, con el estado de cada scope. Si automatizas la creación de keys, léelo de ahí en vez de copiarlo.

​
Un scope no es permiso de escritura

Es el malentendido más común. Para que un POST o un PUT pase hacen falta tres cosas a la vez:

El scope

students:write en el token.

El módulo

El módulo funcional encendido en la institución, más platform_integrations.

El Source of Record

Que ese dominio de datos admita escrituras de este token (masterDomains).
Los tres fallan distinto: SCOPE_REQUIRED, MODULE_DISABLED y SOR_WRITE_FORBIDDEN. Leer el código del error te dice cuál de los tres arreglar.

​
Elegir bien

Empieza con solo lectura. Pon la sincronización a correr, mira la actividad durante unos días, y agrega los scopes de escritura cuando sepas exactamente qué va a escribir el sistema externo. Ampliar un token es un cambio de un minuto; explicar una escritura equivocada en producción, no.
Un par de reglas que ahorran incidentes:
  • Un token por sistema y ambiente. El de pruebas nunca con scopes de escritura sobre producción.
  • Nada de tokens “de todo”. Si una key tiene los doce scopes, el día que se filtre no hay nada que contener.
  • Revisa el SoR antes de pedir :write. Si la institución puso students en external_master, el scope de escritura solo sirve si tu token es el que figura como maestro de ese dominio. Si lo puso en orchestrate_only, no sirve para nadie.