> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credenciales de cliente OAuth

> Aprovisione un cliente de cuenta de servicio con alcance limitado, gestione los secretos de un solo uso y recupérese de forma segura ante solicitudes con resultado incierto.

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](/es/developers/v1/authentication) para elegir entre ambos métodos y comprender cómo encajan las cuentas de servicio.

<Note>
  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.
</Note>

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](/es/developers/developer-hub/service-accounts) 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](/es/developers/v1/regions) 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:

| Variable | Valor |
| - | - |
| `LIVING_SECURITY_API_KEY` | Clave de API de administración |
| `LIVING_SECURITY_REGION` | `us` o `eu` |
| `LIVING_SECURITY_SERVICE_ACCOUNT_ID` | ID de la cuenta de servicio de destino |
| `LIVING_SECURITY_OAUTH_CREATE_KEY` | Clave de reintento conservada previamente |

```python Python theme={null}
import os
import requests

HOSTS = {
    "us": "https://api.us-east-1.livingsecurity.ai/v1",
    "eu": "https://api.eu-west-1.livingsecurity.ai/v1",
}
base = HOSTS[os.environ["LIVING_SECURITY_REGION"]]
response = requests.post(
    f"{base}/oauth_clients",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={
        "Living-Security-Version": "2026-07-01",
        "Idempotency-Key": os.environ["LIVING_SECURITY_OAUTH_CREATE_KEY"],
    },
    json={
        "service_account_id": os.environ["LIVING_SECURITY_SERVICE_ACCOUNT_ID"],
        "scopes": ["organization:read"],
    },
    timeout=(5, 30),
    allow_redirects=False,
)
try:
    if response.status_code != 201:
        raise RuntimeError(
            f"Client creation needs review: HTTP {response.status_code}; "
            f"request_id={response.headers.get('Request-Id', 'unknown')}"
        )
    client = response.json()
    if client.get("object") != "oauth_client" or not client.get("id"):
        raise RuntimeError("Unexpected client receipt; preserve the retry key")
    if client.get("status") != "active" or not client.get("client_secret"):
        raise RuntimeError(
            f"Client {client['id']} needs recovery; no usable secret was returned"
        )
    # Persist client['id'], client['client_id'], and client['client_secret']
    # directly in your secret manager before using the client. Do not print them.
finally:
    response.close()
```

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`.

| Resultado | Siguiente acción |
| - | - |
| `active`, secreto presente | Guarde el secreto de forma segura y continúe con la incorporación. |
| `active`, secreto ausente | El secreto no se puede recuperar. Revoque este cliente, confirme la revocación y cree un reemplazo con una nueva clave de reintento. |
| `pending` | La creación no está confirmada. Conserve la misma clave de reintento. Consulte el recurso para inspeccionar su estado; no cree duplicados para eludir la incertidumbre. |
| `revoked`, `disabled` o `expired` | No utilice este cliente. Confirme la configuración prevista de la cuenta antes de aprovisionar un reemplazo. |
| `409 idempotency_key_reuse` | La solicitud cambió bajo una clave existente. Recupere la operación original antes de decidir si es necesaria una creación independiente. |
| `409 invalid_request` | Compruebe el estado y las concesiones de la cuenta de destino. Si se alcanzó su límite de clientes, complete la limpieza antes de reintentar; cambiar la clave de reintento no libera capacidad. |
| `429` | Respete `Retry-After`; conserve la misma clave y la misma solicitud. |
| `500`, `503` o un tiempo de espera de red agotado | Es posible que se desconozca el resultado. Conserve la clave y los datos de entrada; recupere el recibo antes de crear otro cliente. |
| `401` o `403` | Resuelva el acceso de credenciales, permisos o derechos antes de reintentar. |
| `404` | Confirme la habilitación de OAuth, el host regional y la propiedad del recurso. |

Consulte [errores](/es/developers/v1/errors/overview) 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:

| Operación | Solicitud | Éxito |
| - | - | - |
| Inspeccionar el estado actual | `GET /v1/oauth_clients/{id}` | `200`, recurso de cliente sin secreto |
| Revocar el acceso | `DELETE /v1/oauth_clients/{id}` | `200`, recurso de cliente revocado sin secreto |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.