Esto te permitiría tener un sistema de permisos más detallado, siguiendo el estándar de OAuth2, integrado en tu aplicación OpenAPI (y la documentación de la API).

OAuth2 con scopes es el mecanismo usado por muchos grandes proveedores de autenticación, como Facebook, Google, GitHub, Microsoft, X (Twitter), etc. Lo usan para proporcionar permisos específicos a usuarios y aplicaciones.

* Asegúrate de tener modelos Pydantic bien definidos para tus request bodies y responses.
* Configura los permisos y roles necesarios usando dependencias.
* Nunca guardes contraseñas en texto plano, solo hashes de contraseñas.
* Implementa y utiliza herramientas criptográficas bien conocidas, como pwdlib y JWT tokens, etc.
* Añade controles de permisos más detallados con Scopes de OAuth2 donde sea necesario.
* ...etc.

JWT podría ser usado para otras cosas aparte de identificar un usuario y permitirle realizar operaciones directamente en tu API.

Por ejemplo, podrías identificar un "coche" o un "artículo de blog".

Luego, podrías agregar permisos sobre esa entidad, como "conducir" (para el coche) o "editar" (para el blog).

Normalmente se utilizan para declarar permisos de seguridad específicos, por ejemplo:

* `users:read` o `users:write` son ejemplos comunes.
* `instagram_basic` es usado por Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` es usado por Google.

/// info | Información

En OAuth2 un "scope" es solo un string que declara un permiso específico requerido.

labels.config_parameter=Parámetro de configuración
labels.max_access_count=Número máximo de accesos
labels.number_of_thread=Número de hilos
labels.interval_time=Intervalo
labels.millisec=milisegundos
labels.permissions=Permisos
labels.virtual_hosts=Hosts virtuales
labels.virtual_host=Host virtual
labels.label_type=Etiqueta
labels.file_crawling_button_create=Crear
labels.file_crawling_button_create_job=Crear nuevo trabajo

* para **entrada** el `description` **no será requerido**
* para **salida** será **requerido** (y posiblemente `None`, o en términos de JSON, `null`)

### Modelo para Salida en la Documentación { #model-for-output-in-docs }

Por ejemplo, digamos que tienes 4 endpoints de API (*path operations*):

* `/items/public/`
* `/items/private/`
* `/users/{user_id}/activate`
* `/items/pro/`

entonces podrías agregar diferentes requisitos de permiso para cada uno de ellos solo con dependencias y sub-dependencias:

```mermaid
graph TB

current_user(["current_user"])
active_user(["active_user"])
admin_user(["admin_user"])
paying_user(["paying_user"])

   * "permits / time", thus "1 / rate = time / permits". Thus, "1/rate" (time / permits) times
   * "permits" gives time, i.e., integrals on this function (which is what storedPermitsToWaitTime()
   * computes) correspond to minimum intervals between subsequent requests, for the specified number
   * of requested permits.
   *

   * with the specified number of permits.
   *
   * @param stripes the minimum number of stripes (semaphores) required
   * @param permits the number of permits in each semaphore
   * @return a new {@code Striped<Semaphore>}
   */
  public static Striped<Semaphore> semaphore(int stripes, int permits) {
    return custom(stripes, () -> new PaddedSemaphore(permits));
  }

  /**

Estes escopos representam "permissões".

No OpenAPI (e.g. os documentos da API), você pode definir "esquemas de segurança".

Quando um desses esquemas de segurança utiliza OAuth2, você pode também declarar e utilizar escopos.

Cada "escopo" é apenas uma string (sem espaços).

Eles são normalmente utilizados para declarar permissões de segurança específicas, como por exemplo: