> ## 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 restrito, 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 as exigir. Cada cliente pertence a uma conta de serviço e a uma organização. **O OAuth é opcional:** uma chave de API com escopo restrito é suficiente para uma integração de servidor privada que consiga armazenar e rotacionar uma chave com segurança. Consulte [Autenticação](/pt-BR/developers/v1/authentication) para escolher entre os dois métodos e entender como as contas de serviço se encaixam. O acesso OAuth deve estar habilitado para a sua organização. A sua configuração inicial 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. 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-BR/developers/developer-hub/service-accounts) com apenas as permissões de que a integração precisa. * 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-BR/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ções. ## Criar um cliente `POST /v1/oauth_clients` exige `service_account_id`, uma lista não vazia de `scopes` explícitos e um(a) `Idempotency-Key`. Curingas não são aceitos. Um cliente oferece suporte a até 100 escopos, com comprimento total 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 contando para o limite até que a limpeza remota seja confirmada. Uma reserva abandonada ou uma criação comprovadamente malsucedida antes de o trabalho no provedor começar pode liberar sua vaga com segurança. A chave de nova tentativa ainda pertence à tentativa original; recupere esse recibo antes de decidir se deve criar um substituto. Escolha uma chave de nova tentativa para esta tentativa de criação e persista-a **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 seguintes valores de ambiente por meio do seu gerenciamento habitual de segredos e configurações: | 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 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. Ele não é o ID do recurso da plataforma. Pode ser `null` enquanto a criação estiver pendente. * **`client_secret`** é retornado apenas para a 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 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 reprodução de resposta 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, em seguida, crie um substituto 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 um substituto. | | `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 da credencial, da permissão ou do 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-BR/developers/v1/errors/overview) para obter IDs de solicitação e detalhes de recuperação. Nunca envie um segredo de cliente ou token de acesso em uma solicitação de suporte. ## Inspecionar e revogar Use a sua credencial de gerenciamento e o recurso da plataforma `id`: | 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 das credenciais pode ser concluída posteriormente. Repetir a revogação é seguro e não exige 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 seu endpoint de token regional e verifique se a integração funciona com ele. Mude a integração para o substituto e, em seguida, revogue o recurso antigo. Mantenha uma credencial de gerenciamento independente para que você possa 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 de expirar 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.