Referencia de scopes OAuth

Los scopes definen a qué datos y acciones puede acceder tu aplicación OAuth. Solicita solo los scopes que tu app necesite: es más probable que los usuarios autoricen apps con permisos limitados y concretos.

#Cómo funcionan los scopes

• Los scopes se solicitan durante el flujo de autorización
• Los usuarios ven los permisos solicitados antes de autorizar
• Tu app solo puede acceder a los datos permitidos por los scopes concedidos
• Los scopes no se pueden ampliar sin volver a autorizar

#Formato de los scopes

Los scopes siguen el patrón recurso.permiso:

• transactions.read — Leer datos de transacciones
• invoices.write — Crear, actualizar y eliminar facturas

#Scopes disponibles

#Transacciones

Casos de uso: paneles financieros, control de gastos, gestión de recibos

#Facturas

Casos de uso: automatización de facturación, recordatorios de pago, sincronización contable

#Clientes

Casos de uso: integración con CRM, portales de cliente, sincronización de contactos

#Cuentas bancarias

Casos de uso: seguimiento de la posición de caja, avisos de saldo

#Documentos

Casos de uso: gestión documental, herramientas de copia de seguridad, integraciones OCR

#Bandeja de entrada

Casos de uso: procesamiento de recibos, emparejamiento automático

#Proyectos de seguimiento

Casos de uso: integración con gestión de proyectos, planificación de recursos

#Entradas de seguimiento

Casos de uso: apps de control de tiempo, partes de horas, automatización de facturación

#Equipos

Casos de uso: gestión de equipos, herramientas de incorporación

#Usuarios

Casos de uso: gestión de usuarios, control de acceso

#Etiquetas

Casos de uso: categorización personalizada, automatización de flujos de trabajo

#Informes

Casos de uso: paneles financieros, actualizaciones para inversores, previsiones

#Búsqueda

Casos de uso: búsqueda global, herramientas de descubrimiento de datos

#Notificaciones

Casos de uso: agregadores de notificaciones, sistemas de alertas

#Scopes meta

Para apps que necesitan un acceso amplio, los scopes meta ofrecen atajos prácticos:

Usa los scopes meta con moderación. La mayoría de las apps deberían solicitar scopes específicos.

#Solicitar scopes

Incluye los scopes en la URL de autorización como una lista separada por espacios:

https://app.midday.ai/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=transactions.read%20invoices.read%20customers.read&
  state=STATE

Codifica el parámetro scope para URL (los espacios se convierten en %20).

#Validación de scopes

Cuando los usuarios autorizan tu app:

1. LUMA valida los scopes solicitados contra los scopes registrados de tu app
2. Los scopes inválidos o no registrados provocan que la autorización falle
3. Los usuarios ven exactamente qué permisos están concediendo

Si necesitas scopes adicionales más adelante, los usuarios deberán volver a autorizar tu app.

#Combinaciones de scopes

#Panel financiero

transactions.read invoices.read bank-accounts.read reports.read

#Automatización de facturación

invoices.read invoices.write customers.read customers.write

#Integración de control de tiempo

tracker-projects.read tracker-projects.write tracker-entries.read tracker-entries.write

#Exportación contable

transactions.read invoices.read customers.read documents.read

#Acceso completo de solo lectura

apis.read

#Buenas prácticas

#Solicita los scopes mínimos

Solicita solo lo que necesites. Los usuarios confían más en las apps que piden permisos limitados.

Bien: transactions.read para un rastreador de gastos

Evita: apis.all cuando solo necesitas leer transacciones

#Separa lectura y escritura

Si tu app solo muestra datos, no solicites scopes de escritura:

transactions.read invoices.read

#Agrupa scopes relacionados

Si necesitas facturas, probablemente también necesites clientes:

invoices.read invoices.write customers.read

#Documenta tus necesidades

Explica a los usuarios por qué necesitas cada scope en la descripción de tu app o en el flujo de incorporación.

#Comprobar los scopes concedidos

La respuesta del token incluye los scopes concedidos:

{
  "access_token": "mid_at_xxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "mid_rt_xxxxx",
  "scope": "transactions.read invoices.read"
}

Compáralo con los scopes que solicitaste para confirmar qué se concedió.

#Relacionado

• Crea una app OAuth — Guía de introducción
• Endpoints de la API OAuth — Referencia técnica
• Referencia de la API — Documentación completa de la API