Aplicaciones, tokens y scopes

Una tienda da acceso a un sistema mediante una aplicación: la aplicación decide qué puede hacer el sistema, y sus tokens prueban que una solicitud viene de ella.

Cargando el índice de búsqueda…

Aplicaciones, tokens y scopes

Aplicaciones

Una aplicación es el acceso de un sistema a una tienda: sus scopes, los locales con los que trabaja y, si se configuran, las direcciones desde las que puede llamar. Las aplicaciones se crean en Configuración → API y webhooks; puede hacerlo quien tiene permiso para gestionar la API — por defecto, el dueño — y nadie le da a una aplicación más de lo que tiene.

La aplicación actúa en la tienda como un integrante propio. Los pedidos que crea y el stock que cambia llevan su nombre, así la tienda ve en su historial qué hizo la integración.

La API es parte del plan. Si la tienda pasa a un plan sin ella, las solicitudes reciben 403 integration_api_not_in_plan hasta que vuelva; las aplicaciones y los tokens quedan como estaban.

Scopes

Un scope abre un recurso para leer o para escribir: catalog:read, orders:write. Un scope de escritura incluye el de lectura de su recurso. La tabla de scopes muestra qué endpoints abre cada uno.

Dos scopes agregan campos a las respuestas de otro recurso: costs:read agrega los costos a las variantes del catálogo y a los ítems de los pedidos, y customers:read agrega a los pedidos los contactos, la dirección y el comentario del cliente, y a los comprobantes fiscales el receptor. Sin el scope esos campos no están en la respuesta, no vienen vacíos.

Una solicitud sin el scope de su endpoint recibe 403 insufficient_scope. La respuesta nombra el scope que falta, y la tienda se lo agrega a la aplicación:

Solicitud
curl "https://api.saleya.app/v1/orders" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Respuesta
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="orders:read"

{
  "type": "insufficient_scope",
  "title": "Scope is missing",
  "status": 403,
  "detail": "This request needs the orders:read scope. The store owner grants it in the app access settings.",
  "required_scope": "orders:read",
  "accepted_scopes": [
    "orders:read"
  ]
}

Tokens

  • Un token empieza con saleya_at_. Sus últimos seis caracteres son una suma de control: un token con un error de tipeo se rechaza antes de buscarlo, y los escáneres de secretos reconocen uno filtrado.
  • La tienda guarda solo un hash del token y sus primeros caracteres, por eso el token se muestra una sola vez, al emitirlo.
  • La fecha de vencimiento es opcional. El dueño de la tienda recibe un email antes de que un token venza.
  • Una aplicación tiene como máximo 2 tokens vigentes: uno en uso y otro en reemplazo.

Para rotar un token, emití uno nuevo que reemplace al anterior y elegí cuánto sigue funcionando el anterior. Desplegá el nuevo dentro de ese plazo. La revocación rige desde la siguiente solicitud; eliminar una aplicación revoca todos sus tokens.

type del 401Significado
api_token_missingNo hay encabezado Authorization: Bearer.
api_token_invalidEl formato o la suma de control no coinciden, o no existe ese token.
api_token_expiredPasó la fecha de vencimiento.
api_token_revokedEl token fue revocado, la aplicación eliminada o la tienda cerrada.

Cuidá los tokens

  • Guardá el token en tu servidor. Un token en un navegador, una app móvil o un repositorio es un token filtrado.
  • Limitá la aplicación a las direcciones de tus servidores: una solicitud desde otra dirección recibe 403 ip_not_allowed.
  • El dueño de la tienda recibe un email cuando se emite o revoca un token y cuando cambia el acceso de una aplicación.
  • El registro de solicitudes de la aplicación en el panel guarda cada solicitud durante 30 días: método, ruta, estado y el type de un rechazo, sin cuerpos.
  • Si un token se filtra, revocalo enseguida: la revocación no espera a un reemplazo.
Siguiente guíaTienda de desarrollo