Waafir
Esta página es una traducción automática pendiente de revisión humana. Puede contener errores.

Autenticación

Todas las solicitudes a /v1 están autenticadas. Desde sus propios sistemas, autentíquese con un token de acceso personal (PAT) enviado como token bearer:

Authorization: Bearer waafir_pat_…

Emita, restrinja y revoque tokens en Complementos → Configuración. La guía de tokens de acceso personal explica la emisión, la caducidad (90 días por defecto, 365 como máximo), la visualización única y la revocación. Esas reglas son las mismas para la API de la plataforma. Esta página explica lo que puede hacer un token una vez que lo tiene.

Un token de acceso personal actúa como la persona que lo emitió, dentro de la organización de esa persona. No hay ningún parámetro de organización en ninguna URL ni en ningún cuerpo, porque el token ya la fija.

Las tres comprobaciones del token

Una solicitud autenticada con token tiene que superar estas tres comprobaciones, entre otras. La política de seguridad de la organización y las comprobaciones propias del endpoint también pueden rechazarla (consulte más abajo). Dos de las tres tienen un código propio. Un rechazo por rol puede responder FORBIDDEN, que comparten otros rechazos, así que interprete el código junto con los requisitos del endpoint.

ComprobaciónPreguntaRechazo
Alcance del token¿Cubre el alcance del token lo que hace este endpoint?PAT_SCOPE_INSUFFICIENT 403
Rol¿Tiene quien llama el rol que requiere este endpoint?FORBIDDEN 403, o PAT_ROLE_CEILING 403
Sala de datosEn un token restringido a salas de datos, ¿está esta sala de datos en su lista?PAT_DATAROOM_SCOPE 403

Alcances de los tokens

Un token tiene un único alcance: read, write o admin, en orden creciente de autoridad. Un alcance superior incluye todo lo que está por debajo.

El alcance que necesita un endpoint sigue por defecto su método HTTP:

  • GET, HEAD y OPTIONS necesitan read.
  • Todos los demás métodos (POST, PATCH, PUT, DELETE) necesitan write.

Algunos endpoints declaran un alcance diferente. El caso habitual es un POST que solo ejecuta una consulta, que necesita únicamente read. La referencia de endpoints muestra el alcance que realmente requiere cada endpoint, así que compruébelo allí en lugar de deducirlo del método.

Rol requerido y techo de rol

El alcance indica lo que puede hacer el token. El rol requerido del endpoint indica quién debe ser la persona. Muchos endpoints de /v1 requieren el equipo de la operación (un propietario, administrador o miembro de la organización). Los cambios en el equipo y en las concesiones de acceso, entre otros, requieren un propietario o un administrador. Los inversores y demás invitados no tienen ningún rol del equipo de la operación, por lo que los endpoints del equipo de la operación los rechazan. Otros endpoints no declaran ningún control de rol en la capa de autenticación y, en su lugar, comprueban el acceso dentro del endpoint. Por ejemplo, las rutas de seguimiento de cartera comprueban el complemento de Monitoreo y el acceso de quien llama a Monitoreo. La referencia de endpoints muestra el control de rol de cada endpoint. Cuando no se declara ninguno, tenga en cuenta que el propio endpoint puede rechazar la solicitud.

Un token también registra, como techo, el rol de quien lo emitió en el momento de la emisión. El rol que aplica Waafir es el menor entre el rol actual de quien lo emitió y ese techo. Un miembro al que más tarde se asciende a administrador sigue actuando como miembro a través de un token emitido anteriormente; emita un token nuevo para usar el nuevo rol. Una persona cuyo rol se rebaja pierde la autoridad de inmediato, independientemente de lo que registrara el token. Cualquiera de las dos carencias se rechaza con 403, como FORBIDDEN o PAT_ROLE_CEILING.

Tokens restringidos a salas de datos

Un token emitido con salas de datos concretas seleccionadas, en lugar de Todas las salas de datos, solo llega a esas salas. Una solicitud que menciona cualquier otra sala de datos se rechaza con PAT_DATAROOM_SCOPE. Algunos endpoints que abarcan toda la organización rechazan directamente un token restringido, con el mismo código, porque su respuesta abarca salas de datos que el token no puede ver. Utilice un token sin restricciones para ellos. GET /api/v1/session acepta ambos tipos.

Otros rechazos que puede encontrar

  • 401 UNAUTHORIZED: no hay cabecera Authorization, o el token es desconocido, ha caducado o se ha revocado.
  • 404 para un recurso de otra organización. Un id que pertenece a otra organización se trata como no encontrado, de modo que no se confirma su existencia.
  • Sin excepción de propietario/administrador en los archivos restringidos. En la aplicación, un propietario o administrador de la organización ve todos los archivos restringidos. Un token no: solo llega a un archivo restringido si su propietario lo creó o tiene una concesión sobre él. Una solicitud que menciona uno que no puede leer recibe la misma respuesta que uno inexistente (para /api/v1/grants, un 400 que menciona el archivo, o un 404 para la concesión), con un mensaje que indica que es "not found, or not readable by this credential", de modo que la respuesta nunca confirma que el archivo exista.
  • Política de seguridad de la organización. Si su organización tiene una lista de IP permitidas, una solicitud desde fuera de ella responde IP_BLOCKED. La exigencia de autenticación en dos pasos puede responder MFA_SETUP_REQUIRED o MFA_CHALLENGE_REQUIRED.
  • 429 RATE_LIMITED. Algunos endpoints declaran un límite por minuto para cada identidad, que se muestra en el endpoint. El resto utiliza el valor predeterminado de la plataforma. Espere y vuelva a intentarlo.

La página de códigos de error enumera los códigos conocidos con su significado.