Autenticar una solicitud a la API¶

Las solicitudes de API v3 transmiten un token en la cabecera Authorization: Bearer <valor>. Elija la autenticación según la finalidad de la integración. La clave personal de un usuario y un token API administrativo son entidades distintas con permisos y solicitudes compatibles diferentes.

Token de acceso¶

Inicie sesión con el usuario y la contraseña del usuario:

curl --fail-with-body --request POST \
  --user 'integration:ExamplePassword' \
  'https://watcher.example.com/watcher/client-api/v3/login'

La respuesta contiene:

• access_token — JWT para solicitudes a la API, válido durante una hora.
• refresh_token — identificador de sesión para obtener un nuevo access_token.
• server_info — información del servidor, incluida la versión de Watcher.

Transmita access_token en las solicitudes posteriores:

curl --fail-with-body \
  --header 'Authorization: Bearer <access_token>' \
  'https://watcher.example.com/watcher/client-api/v3/profile'

Para iniciar sesión en Admin API se utiliza POST /watcher/admin-api/v3/login. Requiere acceso de administrador de Watcher; la función de administrador de dominio no es suficiente para este inicio de sesión.

Solicitar un token sin usuario ni contraseña¶

Cuando caduque access_token, repita /login pasando refresh_token:

curl --fail-with-body --request POST \
  --header 'Authorization: Bearer <refresh_token>' \
  'https://watcher.example.com/watcher/client-api/v3/login'

Guarde los tokens de la nueva respuesta. Si la sesión ha finalizado o se ha revocado, deberá volver a iniciar sesión con usuario y contraseña. No cree una sesión nueva antes de cada solicitud: reutilice el token obtenido.

Clave personal de usuario¶

En la interfaz, abra Perfil → Usuario y busque Clave API. Pulse Crear, o Restablecer si la clave ya existe, y confirme. Consulte la guía del perfil para más detalles.

Para emitirla mediante la API, envíe:

curl --fail-with-body --request POST \
  --header 'Authorization: Bearer <access_token>' \
  'https://watcher.example.com/watcher/client-api/v3/users/15/apikey'

Sustituya 15 por el identificador del usuario. Puede obtener su propio identificador mediante GET /profile. La respuesta tiene el formato {"apikey":"<clave>"}. La clave se transmite como Bearer y ejecuta solicitudes con los permisos actuales del usuario. No tiene una caducidad independiente; desactivar al usuario impide utilizarla.

GET /users/{user_id}/apikey lee una clave existente. Repetir POST la sustituye: la clave anterior deja de servir para nuevas solicitudes. El propio usuario o quien tenga permiso para acceder a sus datos protegidos, incluido un administrador de Watcher, puede emitir o leer la clave. Protéjala como una contraseña.

Token API con ámbitos de acceso¶

Un administrador del sistema Watcher puede crear un token independiente mediante POST /watcher/admin-api/v3/api_tokens. El cuerpo contiene name y una lista permissions con scopes. Este token solo sirve para operaciones que admitan el ámbito correspondiente; no sustituye universalmente a una clave de usuario.

Por ejemplo, la generación de inicio de sesión automático utiliza el ámbito autologin/generate:

{
  "name": "billing-autologin",
  "permissions": [{"scopes": ["autologin/generate"], "execute": true}]
}

El key obtenido se transmite como Bearer. Consulte el uso en inicio de sesión automático.

Tokens de configuración del dominio¶

Para la integración de facturación del lado del servidor con Lumika se proporcionan tokens de configuración de dominio independientes. Su emisión mediante Configuraciones → Tokens API, los ámbitos config/ y su ciclo de vida se describen en la guía de integración de Lumika. Un administrador del sistema o de dominio gestiona este formulario. En él se seleccionan permisos de configuración; el ámbito autologin/generate del ejemplo anterior no se emite desde este formulario. La clave personal del usuario se crea en Perfil.

Comprobar errores de acceso¶

• 401 — compruebe el token y el estado de la sesión; si el JWT ha caducado, intente renovarlo mediante /login.
• 403 — compruebe la función del usuario, sus permisos en la Organización concreta y los permisos del token. Un usuario readonly no puede ejecutar solicitudes de modificación.
• 400 — compruebe el cuerpo y los parámetros de la solicitud con la referencia de la API.