Autenticación

Cada petición a la API de partners lleva una credencial, en el lugar estándar:

Authorization: Bearer brp_<prefix>.<secret>

No hay ningún otro esquema. Ni clave en la cadena de consulta, ni basic auth, ni cookie. Una petición sin esa cabecera, o con un valor malformado, responde 401 antes de que se evalúe nada más.

Qué es una clave

Una clave tiene dos mitades separadas por un punto.

BackResto almacena el prefijo y un resumen con clave del secreto. El secreto en sí no se almacena y no se puede recuperar: ni usted, ni soporte, ni la base de datos. Si se pierde, revoque la clave y cree otra.

Concesiones: restaurante × permiso

Una clave no es «una cuenta con privilegios». Es una lista de concesiones explícitas, cada una un par:

Hay veintiséis permisos, y vale la pena aprenderse la gramática una vez:

Todos los permisos terminan en :read. No hay ningún permiso de partner que escriba, y no se puede crear: el lado de escritura de esta API pertenece a la aplicación BackResto, y una clave de partner es estructuralmente incapaz de tener uno.

Una clave con deliveries:read concedido en restaurant-1 y restaurant-2, y delivery-images:read solo en restaurant-1, lee las fotografías del primer restaurante y obtiene 403 para el segundo. Es una configuración admitida, no un error: algunas integraciones quieren los registros sin las fotos.

Pida los que use. Veintiséis permisos no son un menú que marcar entero: el restaurante lee la lista antes de aceptarla, y una solicitud de todo tarda más en salir adelante que una solicitud de las cuatro colecciones que su producto lee de verdad.

Tres modos de fallo, deliberadamente distintos:

• 404 — la clave no tiene ninguna concesión para ese restaurante. La API no le dice a quien llama sin autorización si un restaurante existe.
• 403 — la clave tiene una concesión para ese restaurante, pero no el permiso que este endpoint necesita.
• 401 — entre otras cosas, una clave que se ha quedado sin ninguna concesión. Una clave a la que se le retira la última concesión deja de autenticarse en lugar de responder vacío.

Para ver qué tiene realmente una clave, pregúnteselo: GET /v1/restaurants lista los restaurantes con sus permisos, y GET /v1/restaurants/{id}/collections lista las colecciones que abre.

Quién puede emitirla

Nosotros, previa solicitud, y solo para restaurantes que lo hayan aceptado. Consulte Obtener una clave para saber qué enviar y qué recibe a cambio.

Las concesiones se fijan cuando se aprovisiona la clave y solo se cambian mediante otra solicitud. No hay ninguna vía —ni para usted ni para nosotros— que amplíe una clave sin que el restaurante vuelva a aceptarlo.

Caducidad y revocación

Una clave no caduca por sí sola, salvo que haya pedido una que lo haga. Sigue siendo válida hasta que se revoca.

La revocación es inmediata: la siguiente petición con esa clave responde 401, la misma respuesta que obtiene una clave desconocida o caducada. No se puede deshacer, y no hace falta: un reemplazo es una clave nueva, no una restaurada.

Rotar sin interrupciones

Una integración puede tener dos claves activas a la vez, así que la rotación no necesita ventana de mantenimiento. Pídanos una rotación y este es el orden en que ocurre:

1. Emitimos una segunda clave con los mismos restaurantes y permisos.
2. Usted despliega el nuevo secreto y nos avisa cuando está activo en todas partes.
3. Comprobamos que la clave antigua ha dejado de usarse: podemos ver cuándo se autenticó por última vez cada clave, que es la señal que hace seguro el paso 4.
4. Revocamos la antigua.

Rote con la periodicidad que elija, y empiece la solicitud unos días antes de querer que la clave antigua desaparezca: los pasos 2 y 3 hay que coordinarlos entre usted y nosotros, y todo el sentido del orden anterior es que nada esté muerto ni un instante.

Higiene

• Guárdela nada más recibirla y borre el correo. Hecho eso, el secreto existe exactamente en dos sitios: su gestor de secretos y la cabecera Authorization.
• Una clave por despliegue, no una por empresa. Una clave de staging filtrada nunca debería ser un incidente de producción, y una revocación nunca debería tumbar más que aquello que se filtró.
• Nunca nos envíe el secreto: ni en un ticket, ni para identificar una clave. El prefijo público la nombra sin ambigüedad y se puede escribir en cualquier sitio sin riesgo.
• Vigile los 401 en su propia monitorización. Una clave que empieza a fallar ha sido revocada, y la respuesta es una conversación, no un bucle de reintentos.