Alcances (scopes)

La lista canónica de alcances y cómo limitar cada llave de API al mínimo privilegio necesario.

Los alcances limitan lo que cada llave de API puede hacer. Emite llaves restringidas por caso de uso: una de solo lectura para reportes, una de escritura para tu servicio de fulfillment.

Lista canónica

Alcance	Permite
`*`	Acceso total (valor por defecto en llaves nuevas)
`shipments:read`	Leer envíos y su detalle
`shipments:write`	Crear y actualizar envíos
`labels:read`	Leer detalles de guías
`labels:write`	Comprar guías (incluida la compra en una llamada, que además requiere `shipments:write`)
`addresses:read`	Leer direcciones guardadas
`addresses:write`	Crear y actualizar direcciones
`wallet:read`	Leer saldo y transacciones del monedero
`wallet:write`	Iniciar fondeos del monedero
`webhooks:read`	Leer endpoints de webhook y sus intentos de entrega
`webhooks:write`	Crear, actualizar y eliminar endpoints de webhook
`organizations:read`	Leer la organización y sus miembros
`organizations:write`	Actualizar configuración y gestionar miembros
`api_keys:read`	Leer la lista de llaves y sus registros de uso
`api_keys:write`	Crear, actualizar, rotar y revocar llaves
`rates:read`	Obtener cotizaciones
`carrier_preferences:write`	Configurar paqueterías habilitadas y credenciales de tu propia cuenta
`carrier_services:read`	Leer el catálogo de servicios
`tracking:read`	Leer eventos de rastreo
`trackers:read`	Leer rastreadores registrados
`trackers:write`	Registrar y eliminar rastreadores
`orders:read`	Leer órdenes
`orders:write`	Crear, actualizar, cancelar y eliminar órdenes
`batches:read`	Leer lotes
`batches:write`	Crear lotes y manifiestos
`products:read`	Leer el catálogo de productos
`products:write`	Crear, actualizar y eliminar productos
`notification_settings:read`	Leer los interruptores de notificaciones al destinatario, su marca y sus plantillas
`notification_settings:write`	Actualizar los interruptores, asuntos y marca de las notificaciones
`shipping_rules:read`	Leer y previsualizar reglas de automatización
`shipping_rules:write`	Crear, actualizar, reordenar y eliminar reglas
`insurance_claims:read`	Leer reclamaciones de seguro
`insurance_claims:write`	Presentar reclamaciones y administrar su estado

Cómo se aplican

Las sesiones del dashboard tienen acceso implícito completo. Los alcances aplican a las llaves de API.
Una llave con scopes: ["*"] accede a todo.
Si a una llave le falta un alcance requerido, la petición devuelve 403 INSUFFICIENT_SCOPE con los alcances faltantes listados en details.

Crea llaves restringidas

curl -X POST https://api.sendit.mx/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Servicio de fulfillment",
    "environment": "LIVE",
    "scopes": ["shipments:read", "labels:write"]
  }'

Restringe por IP (opcional)

Beta Esta función está en beta. Su comportamiento puede ajustarse antes de la versión final.

Limita una llave a IPs o bloques CIDR específicos. Por defecto la lista está vacía (todas las IPs permitidas):

curl -X POST https://api.sendit.mx/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Servidor de fulfillment",
    "scopes": ["labels:write"],
    "ipAllowlist": ["203.0.113.0/24", "198.51.100.42"]
  }'

Las peticiones desde IPs fuera de la lista devuelven 403 IP_NOT_ALLOWED.

Rota llaves con ventana de gracia

Rotar crea un reemplazo con los mismos alcances y la misma lista de IPs. La llave anterior sigue siendo válida 24 horas para que las peticiones en vuelo terminen de drenar:

curl -X POST https://api.sendit.mx/v1/api-keys/{id}/rotate \
  -H "Authorization: Bearer <jwt>"

Durante la ventana verás ambas llaves en GET /v1/api-keys: la que rota y la nueva.