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

# Credenciais de cliente OAuth

> Provisione um cliente de conta de serviço com escopo definido, trate segredos de uso único e recupere-se com segurança de solicitações com resultado incerto.

Use as credenciais de cliente OAuth quando a sua integração de backend precisar de tokens de
acesso de curta duração ou quando a sua política de segurança os exigir. Cada cliente pertence a
uma conta de serviço e a uma organização. **O OAuth é opcional:** uma chave de API com escopo
definido é suficiente para uma integração privada de servidor que consiga armazenar
e rotacionar uma chave com segurança. Consulte [Autenticação](/pt/developers/v1/authentication) para escolher
entre os dois métodos e entender como as contas de serviço se encaixam.

<Note>
  O acesso OAuth deve estar habilitado para a sua organização. A sua configuração fornece o
  endpoint de token regional, o emissor, o público-alvo (audience) e o método de autenticação do cliente.
  Se precisar dessas configurações ou não conseguir acessar o gerenciamento de clientes, entre em contato com o
  Suporte da Living Security.
</Note>

A concessão de credenciais de cliente representa a sua conta de serviço. Ela não autentica uma pessoa
nem solicita que um cliente autorize um aplicativo. A autorização delegada por meio de um
navegador é um recurso OAuth distinto e não é oferecida por estas operações.

## Antes de começar

* Crie uma [conta de serviço](/pt/developers/developer-hub/service-accounts) com apenas
  as permissões de que a integração necessita.
* Use uma credencial de gerenciamento com `service_account:manage` e cada permissão
  que você deseja conceder ao novo cliente. A conta de destino também deve possuir essas
  permissões. Um cliente não pode ampliar a autoridade de nenhuma das contas.
* Escolha a [região](/pt/developers/v1/regions) da organização. As credenciais de API e
  os tokens de acesso OAuth pertencem ao host de API regional correspondente.
* Mantenha o segredo do cliente e os tokens no armazenamento de segredos do seu servidor. Nunca os coloque
  em código de navegador, aplicativos móveis, controle de versão ou logs de solicitação.

## Criar um cliente

`POST /v1/oauth_clients` requer `service_account_id`, uma lista não vazia de
`scopes` explícitos e um `Idempotency-Key`. Curingas não são aceitos. Um cliente oferece suporte a
até 100 escopos, com um comprimento combinado de no máximo 4.096 caracteres. Cada conta
de serviço pode ter no máximo 20 clientes ou operações de criação/limpeza não resolvidas.
A revogação nega imediatamente o acesso à API. Um cliente ou uma criação incerta no provedor
continua a contar para o limite até que a limpeza remota seja confirmada.
Uma reserva abandonada ou uma criação comprovadamente falha antes de o trabalho no provedor
ter começado pode liberar sua vaga com segurança. A chave de nova tentativa dela ainda pertence à tentativa
original; recupere esse recibo antes de decidir se deve criar uma substituição.

Escolha uma chave de nova tentativa para esta tentativa de criação e a persista **antes** de enviar
a solicitação. Use de 1 a 255 caracteres ASCII visíveis, sem espaços. Reutilize-a com a
mesma conta, os mesmos escopos, a mesma entidade de gerenciamento, a mesma região e a mesma versão da API após uma
resposta perdida. Rotacionar a credencial de gerenciamento na mesma conta de serviço
não cria uma nova identidade de nova tentativa.

Instale o pacote `requests` do Python. Carregue os valores de ambiente a seguir por meio
do seu gerenciamento normal de segredos e configuração:

| Variável | Valor |
| - | - |
| `LIVING_SECURITY_API_KEY` | Chave de API de gerenciamento |
| `LIVING_SECURITY_REGION` | `us` ou `eu` |
| `LIVING_SECURITY_SERVICE_ACCOUNT_ID` | ID da conta de serviço de destino |
| `LIVING_SECURITY_OAUTH_CREATE_KEY` | Chave de nova tentativa persistida anteriormente |

```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()
```

O exemplo faz uma única solicitação e mantém o resultado na memória. Adicione a operação de gravação
do seu gerenciador de segredos no ponto indicado antes de executá-lo em produção.
Ele exige deliberadamente uma decisão após um resultado incerto, em vez de
criar silenciosamente outro cliente. Exceções de rede também exigem as etapas de recuperação abaixo.

As respostas de criação e de recibo usam `201` e contêm um recurso `oauth_client`
com `id`, `service_account_id`, `client_id`, `scopes`, `status`, `created_at` e
`client_secret`. As respostas são marcadas como `Cache-Control: no-store`.

* **`id`** identifica o recurso da plataforma. Salve-o para consulta e revogação.
* **`client_id`** identifica o cliente durante a troca de tokens. Não é o
  ID do recurso da plataforma. Pode ser `null` enquanto a criação está pendente.
* **`client_secret`** é retornado somente à solicitação que conclui a criação.
  Toda solicitação de criação repetida retorna `null`, inclusive uma nova tentativa após uma resposta
  de sucesso perdida. A consulta nunca retorna um segredo.

## Recuperar-se de uma resposta perdida ou interrompida

Repita a mesma solicitação de criação com a chave de nova tentativa salva para recuperar o recibo
do recurso. O recibo reflete o estado atual, portanto um cliente revogado permanece revogado.
Esta operação não usa o contrato geral de repetição de respostas em cache de 24 horas
e não retorna um cabeçalho `Idempotent-Replayed`.

| Resultado | Próxima ação |
| - | - |
| `active`, segredo presente | Salve o segredo com segurança e continue a integração. |
| `active`, segredo ausente | O segredo não pode ser recuperado. Revogue este cliente, confirme a revogação e crie uma substituição usando uma nova chave de nova tentativa. |
| `pending` | A criação não foi confirmada. Mantenha a mesma chave de nova tentativa. Consulte o recurso para inspecionar o estado; não crie duplicatas para contornar a incerteza. |
| `revoked`, `disabled` ou `expired` | Não use este cliente. Confirme a configuração pretendida da conta antes de provisionar uma substituição. |
| `409 idempotency_key_reuse` | A solicitação foi alterada sob uma chave existente. Recupere a operação original antes de decidir se é necessária uma criação separada. |
| `409 invalid_request` | Verifique o status e as concessões da conta de destino. Se o limite de clientes foi atingido, conclua a limpeza antes de tentar novamente; alterar a chave de nova tentativa não libera capacidade. |
| `429` | Respeite `Retry-After`; mantenha a mesma chave e a mesma solicitação. |
| `500`, `503` ou um tempo limite de rede | O resultado pode ser desconhecido. Preserve a chave e os dados de entrada; recupere o recibo antes de criar outro cliente. |
| `401` ou `403` | Resolva o acesso relacionado à credencial, à permissão ou ao direito de uso antes de tentar novamente. |
| `404` | Confirme a habilitação do OAuth, o host regional e a propriedade do recurso. |

Consulte [erros](/pt/developers/v1/errors/overview) para obter IDs de solicitação e detalhes de recuperação.
Nunca envie um segredo de cliente ou um token de acesso com uma solicitação de suporte.

## Inspecionar e revogar

Use a sua credencial de gerenciamento e o `id` do recurso da plataforma:

| Operação | Solicitação | Sucesso |
| - | - | - |
| Inspecionar o estado atual | `GET /v1/oauth_clients/{id}` | `200`, recurso de cliente sem segredo |
| Revogar o acesso | `DELETE /v1/oauth_clients/{id}` | `200`, recurso de cliente revogado sem segredo |

A revogação bloqueia as solicitações de API subsequentes do cliente, inclusive as solicitações com
tokens já emitidos. Ela não cancela o trabalho já aceito pela API.
A limpeza remota de credenciais pode ser concluída posteriormente. Repetir a revogação é seguro e
não requer chave de nova tentativa. Continue usando a credencial de gerenciamento se o cliente
que está sendo revogado for ele próprio um chamador da API.

## Rotacionar sem perder o acesso

Crie um segundo cliente com o limite de escopo necessário. Salve o segredo dele, obtenha um
token usando o endpoint de token regional e verifique se a integração funciona
com ele. Altere a integração para a substituição e, em seguida, revogue o recurso antigo.
Mantenha uma credencial de gerenciamento independente para poder se recuperar de uma implantação malsucedida.

Os tokens de acesso não podem conceder mais do que os escopos do cliente e as permissões
atuais da conta de serviço. A remoção de permissões da conta ou a revogação de um cliente têm
precedência sobre o tempo de vida restante de um token. Não trate um token em cache como prova
de que a autorização ainda é válida. Obtenha um novo token de acesso antes da expiração
autenticando o cliente novamente; esta concessão não usa tokens de atualização.


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