> ## 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. # Guia de início rápido da API > Crie uma conta de serviço e uma chave de API no Developer Hub, autentique-se com Basic auth e faça sua primeira solicitação à API Pública da Living Security. Crie uma conta de serviço e uma chave de API no Developer Hub e, em seguida, faça sua primeira solicitação. Este guia de início rápido usa autenticação por chave de API; não é necessário um cliente OAuth. Consulte [Autenticação](/pt-BR/developers/v1/authentication) se sua integração exigir tokens de acesso OAuth de curta duração. ## Pré-requisitos * Acesso de administrador ao Painel da Living Security. * O Developer Hub visível em **Configurações → Integrações & Developers → Developer Hub**. ## Criar credenciais No Developer Hub, abra a guia **Service accounts** e crie uma conta. Atribua um nome descritivo (por exemplo, `reporting-pipeline`) e conceda as permissões que suas chaves poderão usar — para este guia, `organization:read` é suficiente. As permissões da conta são o limite máximo para todas as chaves criadas nela: uma chave nunca pode fazer mais do que a conta de serviço permite. Abra a página de detalhes da conta de serviço e crie uma chave. Escolha as permissões de que esta chave específica precisa (um subconjunto das da conta) e uma expiração — 30, 90 ou 365 dias, ou um período personalizado. A expiração é obrigatória. O segredo da chave começa com `lsk_live_` e é exibido **uma única vez**. Copie-o imediatamente para um gerenciador de segredos; ele não poderá ser recuperado depois. Nunca faça commit de segredos de chaves de API no controle de versão nem os incorpore em código do lado do cliente. Qualquer pessoa que tenha o segredo pode agir com as permissões da chave. Chame o host `/v1` regional correspondente à residência de dados da organização. As chaves se autenticam somente nesse host. | Região | URL base | | - | - | | US | `https://api.us-east-1.livingsecurity.ai/v1` | | EU | `https://api.eu-west-1.livingsecurity.ai/v1` | Consulte [Regiões](/pt-BR/developers/v1/regions) se você não tiver certeza de qual host usar. Uma chave válida enviada para a outra região falha com `unauthorized`. Use o menu suspenso de região no exemplo abaixo para alternar o host. Carregue `LIVING_SECURITY_API_KEY` do seu gerenciador de segredos no ambiente do processo que fará a solicitação. Os exemplos abaixo o leem sem incorporar um segredo ao código-fonte. Para Python, instale `requests` primeiro. Chame a API com o segredo no campo de senha ou de nome de usuário da autenticação HTTP Basic — qualquer um funciona, de modo que clientes que exigem o preenchimento de ambos os campos (como o conector Web do Power BI) possam colocar um valor provisório como `apikey` no outro campo. ```bash cURL theme={null} curl --fail-with-body --connect-timeout 5 --max-time 30 \ https://api.eu-west-1.livingsecurity.ai/v1/organization \ -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \ -H "Living-Security-Version: 2026-07-01" ``` ```bash cURL (key as username) theme={null} curl --fail-with-body --connect-timeout 5 --max-time 30 \ https://api.eu-west-1.livingsecurity.ai/v1/organization \ -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \ -H "Living-Security-Version: 2026-07-01" ``` ```python Python theme={null} import os import requests BASE = "https://api.eu-west-1.livingsecurity.ai/v1" response = requests.get( f"{BASE}/organization", auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]), headers={"Living-Security-Version": "2026-07-01"}, timeout=(5, 30), allow_redirects=False, ) response.raise_for_status() if response.status_code != 200: raise RuntimeError("Unexpected response; check your regional API URL") print(response.json()) ``` Uma resposta bem-sucedida retorna sua organização: ```json Response theme={null} { "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b", "object": "organization", "name": "Example Corp", "region": "eu", "plan": "enterprise", "subscription_status": "active", "created_at": "2024-03-12T18:04:11.000Z" } ``` Se você receber essa resposta, suas credenciais funcionam. A solicitação também aparece na guia **Request logs** do Developer Hub em instantes. A autenticação Bearer com o mesmo segredo (`Authorization: Bearer lsk_live_...`) também funciona. A autenticação Basic existe para que ferramentas que só aceitam nome de usuário/senha — como o conector Web do Power BI — possam se conectar. ## Como a autenticação funciona * **A credencial determina a organização.** As solicitações `/v1` não contêm seletor de tenant: nem segmento de caminho de organização, nem cabeçalho de organização. O envio de um cabeçalho `x-organization-id` é rejeitado com `invalid_request`. O host ainda deve corresponder à região dessa organização. Consulte [Regiões](/pt-BR/developers/v1/regions). * **As permissões são verificadas por operação.** Cada operação `/v1` exige uma permissão nomeada (por exemplo, `GET /v1/organization` exige `organization:read`). Uma chave sem a permissão recebe `403` com o código `insufficient_permission`. * **As chaves expiram e podem ser rotacionadas sem tempo de inatividade.** Consulte [Chaves de API](/pt-BR/developers/developer-hub/api-keys) para saber como fazer a rotação com um período de sobreposição. ## Como ler respostas de erro Todo erro `/v1` é `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) com um código de máquina estável. Por exemplo, uma solicitação com credencial ausente ou desconhecida retorna: ```json 401 Unauthorized theme={null} { "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "No valid API credential was provided.", "code": "unauthorized", "request_id": "req_...", "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized", "retryable": false } ``` Ramifique a lógica com base em `code`, nunca em `detail`. Siga `doc_url` para ver as etapas de resolução e inclua `request_id` ao entrar em contato com o suporte — ele corresponde ao cabeçalho de resposta `Request-Id` e aos logs de solicitações do Developer Hub. O conjunto completo de códigos está na [referência de erros](/pt-BR/developers/v1/errors/overview). ## Versões do contrato Toda resposta ecoa a versão do contrato que a atendeu no cabeçalho `Living-Security-Version`, junto com um cabeçalho `Request-Id` para correlação. Você pode fixar uma solicitação em uma versão publicada do contrato por data: ```bash cURL theme={null} curl --fail-with-body --connect-timeout 5 --max-time 30 \ https://api.eu-west-1.livingsecurity.ai/v1/organization \ -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \ -H "Living-Security-Version: 2026-07-01" ``` A versão é resolvida nesta ordem: o cabeçalho da solicitação, se presente; caso contrário, o padrão fixado da conta de serviço; caso contrário, a versão publicada mais recente. Solicitar uma versão que não está publicada (ou que passou da data de desativação) retorna `400` com o código `unsupported_version`. As versões publicadas e suas alterações estão listadas no [changelog da API](/pt-BR/developers/v1/changelog). ## Solução de problemas da primeira solicitação | Resultado | Próxima ação | | - | - | | `401 unauthorized` | Verifique o segredo, sua expiração e a região da organização. Não tente outros hosts com uma credencial ativa. | | `403 insufficient_permission` | Conceda `organization:read` tanto à conta de serviço quanto à sua chave. | | `400 unsupported_version` | Escolha uma versão publicada no [changelog](/pt-BR/developers/v1/changelog). | | `429 rate_limited` | Aguarde `Retry-After`; siga o [exemplo de nova tentativa limitada](/pt-BR/developers/v1/rate-limits). | | Tempo limite de rede | Verifique a conectividade e tente novamente esta leitura dentro do orçamento de novas tentativas da sua aplicação. | Para outros erros, siga `doc_url` da resposta. Guarde `Request-Id` para o suporte; nunca inclua o cabeçalho Authorization nem sua chave de API em um chamado. ## Próximas etapas Escolha o host `/v1` dos EUA ou da UE para a organização. Percorra listas com `page_token` e o envelope de lista. Entenda os orçamentos de solicitações e trate respostas `429`. Todos os códigos de erro, seu status HTTP e como resolvê-los. Gerencie contas de serviço, chaves de API e logs de solicitações. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.