> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edtools.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> Los doce scopes de v1, qué abre cada uno y por qué un scope no basta para escribir.

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

<Tabs>
  <Tab title="Activos">
    | Scope              | Permite                                                                          |
    | ------------------ | -------------------------------------------------------------------------------- |
    | `students:read`    | Consultar estudiantes y sus campos públicos de integración.                      |
    | `students:write`   | Crear, actualizar y sincronizar estudiantes cuando el SoR lo permite.            |
    | `admissions:read`  | Consultar postulaciones y estados del pipeline de admisiones.                    |
    | `admissions:write` | Crear, actualizar y vincular contactos a postulaciones cuando el SoR lo permite. |
    | `payments:read`    | Consultar pagos y obligaciones de la institución.                                |
    | `payments:write`   | Crear, actualizar y sincronizar pagos cuando el SoR lo permite.                  |
    | `programs:read`    | Leer el catálogo vigente de programas académicos.                                |
    | `courses:read`     | Leer el catálogo vigente de cursos.                                              |
    | `vault:read`       | Leer tipos de documento, documentos, requisitos y solicitudes.                   |
    | `vault:write`      | Crear y actualizar documentos y solicitudes del Vault.                           |
    | `forms:read`       | Leer plantillas de formulario y sus respuestas.                                  |
  </Tab>

  <Tab title="Reservados">
    | Scope         | Estado                                                                                      |
    | ------------- | ------------------------------------------------------------------------------------------- |
    | `forms:write` | Declarado en el catálogo, **sin endpoints en v1**. No lo asignes: no habilita nada todavía. |
  </Tab>
</Tabs>

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**:

<CardGroup cols={3}>
  <Card title="El scope" icon="key">
    `students:write` en el token.
  </Card>

  <Card title="El módulo" icon="toggle-on">
    El módulo funcional encendido en la institución, más `platform_integrations`.
  </Card>

  <Card title="El Source of Record" icon="crown">
    Que ese dominio de datos admita escrituras de este token (`masterDomains`).
  </Card>
</CardGroup>

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

<Tip>
  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.
</Tip>

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.