Skip to main content
Utilice las credenciales de cliente OAuth cuando su integración de backend necesite tokens de acceso de corta duración o cuando su política de seguridad lo exija. Cada cliente pertenece a una cuenta de servicio y a una organización. OAuth es opcional: una clave de API con alcance limitado es suficiente para una integración privada de servidor que pueda almacenar y rotar una clave de forma segura. Consulte Autenticación para elegir entre ambos métodos y comprender cómo encajan las cuentas de servicio.
El acceso a OAuth debe estar habilitado para su organización. Su configuración inicial proporciona el endpoint de tokens regional, el emisor, la audiencia y el método de autenticación del cliente. Si necesita estos valores de configuración o no puede acceder a la gestión de clientes, comuníquese con el Soporte de Living Security.
La concesión de credenciales de cliente representa a su cuenta de servicio. No inicia sesión con una persona ni solicita a un cliente que autorice una aplicación. La autorización delegada mediante un navegador es una capacidad de OAuth independiente y estas operaciones no la ofrecen.

Antes de comenzar

  • Cree una cuenta de servicio con únicamente los permisos que necesita la integración.
  • Utilice una credencial de administración con service_account:manage y cada permiso que desee conceder al nuevo cliente. La cuenta de destino también debe contar con esos permisos. Un cliente no puede ampliar la autoridad de ninguna de las dos cuentas.
  • Elija la región de la organización. Las credenciales de API y los tokens de acceso OAuth corresponden al host de API regional que coincida.
  • Mantenga el secreto del cliente y los tokens en el almacenamiento de secretos de su servidor. No los incluya nunca en código de navegador, aplicaciones móviles, control de código fuente ni registros de solicitudes.

Crear un cliente

POST /v1/oauth_clients requiere service_account_id, una lista no vacía de scopes explícitos y una Idempotency-Key. No se aceptan comodines. Un cliente admite hasta 100 alcances, con una longitud combinada máxima de 4,096 caracteres. Cada cuenta de servicio puede tener como máximo 20 clientes u operaciones de creación o limpieza sin resolver. La revocación deniega de inmediato el acceso a la API. Un cliente, o una creación incierta en el proveedor, sigue contando para el límite hasta que se confirme la limpieza remota. Una reserva abandonada, o una creación que se haya demostrado fallida antes de que comenzara el trabajo del proveedor, puede liberar su espacio de forma segura. Su clave de reintento sigue perteneciendo al intento original; recupere ese recibo antes de decidir si se debe crear un reemplazo. Elija una clave de reintento para este intento de creación y consérvela de forma persistente antes de enviar la solicitud. Utilice entre 1 y 255 caracteres ASCII visibles, sin espacios. Reutilícela con la misma cuenta, los mismos alcances, la misma entidad de administración, la misma región y la misma versión de API después de una respuesta perdida. Rotar la credencial de administración bajo la misma cuenta de servicio no crea una nueva identidad de reintento. Instale el paquete requests de Python. Cargue los siguientes valores de entorno mediante su gestión habitual de secretos y configuración:
Python
El ejemplo realiza una sola solicitud y conserva el resultado en memoria. Agregue la operación de escritura de su gestor de secretos en el punto indicado antes de ejecutarlo en producción. El ejemplo exige deliberadamente una decisión tras un resultado incierto, en lugar de crear otro cliente de forma silenciosa. Las excepciones de red también requieren los pasos de recuperación que se describen a continuación. Las respuestas de creación y de recibo utilizan 201 y contienen un recurso oauth_client con id, service_account_id, client_id, scopes, status, created_at y client_secret. Las respuestas se marcan con Cache-Control: no-store.
  • id identifica el recurso de la plataforma. Guárdelo para su consulta y revocación.
  • client_id identifica al cliente durante el intercambio de tokens. No es el ID del recurso de la plataforma. Puede ser null mientras la creación está pendiente.
  • client_secret se devuelve únicamente a la solicitud que completa la creación. Toda solicitud de creación repetida devuelve null, incluido un reintento tras perder la respuesta de éxito. La consulta nunca devuelve un secreto.

Recuperarse de una respuesta perdida o interrumpida

Repita la misma solicitud de creación con la clave de reintento guardada para recuperar el recibo del recurso. El recibo refleja el estado actual, por lo que un cliente revocado permanece revocado. Esta operación no utiliza el contrato general de reproducción de respuestas en caché de 24 horas y no devuelve un encabezado Idempotent-Replayed. Consulte errores para obtener los ID de solicitud y los detalles de recuperación. No envíe nunca un secreto de cliente ni un token de acceso con una solicitud de soporte.

Inspeccionar y revocar

Utilice su credencial de administración y el id del recurso de la plataforma: La revocación bloquea las solicitudes posteriores a la API del cliente, incluidas las realizadas con tokens ya emitidos. No cancela el trabajo que la API ya haya aceptado. La limpieza remota de credenciales puede completarse más tarde. Repetir la revocación es seguro y no requiere clave de reintento. Continúe utilizando la credencial de administración si el cliente que se revoca es, a su vez, un llamador de la API.

Rotar sin perder el acceso

Cree un segundo cliente con el límite de alcances requerido. Guarde su secreto, obtenga un token mediante su endpoint de tokens regional y verifique que la integración funcione con él. Cambie la integración al reemplazo y, a continuación, revoque el recurso anterior. Conserve una credencial de administración independiente para poder recuperarse de un despliegue fallido. Los tokens de acceso no pueden conceder más de lo que permiten los alcances del cliente y los permisos actuales de la cuenta de servicio. Quitar permisos de la cuenta o revocar un cliente tiene prioridad sobre la vigencia restante de un token. No considere un token almacenado en caché como prueba de que la autorización sigue siendo válida. Obtenga un nuevo token de acceso antes de que expire autenticando de nuevo al cliente; esta concesión no utiliza tokens de actualización.