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

# Quick Start: Primeira chamada de API em 2 minutos

> Crie uma API Key e faça seu primeiro request com 1 linha de cURL.

Esse fluxo é ideal pra **scripts, jobs e sincronizações server-to-server** — qualquer coisa que não envolve um usuário interativo. Se você quer que o usuário final autentique, use [Login com a Cativa](/pt-BR/get-started/quickstart-sign-in).

<Steps>
  <Step title="Crie uma API Key">
    No Console, vá em **Developers > API Keys > Create**.

    Dê um nome (ex: `Sync HubSpot prod`) e clique **Create**. A chave aparece **uma única vez** no formato:

    ```
    cativa_live_8c1d4e2a3b5f4d8a9c6e7f0b1a2d3e4f
    ```

    Copie e guarde com segurança — não dá pra ver de novo. Se perder, gere outra e revogue essa.
  </Step>

  <Step title="Faça seu primeiro request">
    Pegue os dados do usuário associado à chave (endpoint canônico para validar credencial):

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://apis.cativalab.digital/tenant/v1/auth/me \
        -H "Authorization: Bearer cativa_live_8c1d4e2a3b5f4d8a9c6e7f0b1a2d3e4f"
      ```

      ```js Node theme={null}
      const res = await fetch('https://apis.cativalab.digital/tenant/v1/auth/me', {
        headers: {
          'Authorization': `Bearer ${process.env.CATIVA_API_KEY}`
        }
      });
      const me = await res.json();
      ```

      ```python Python theme={null}
      import requests
      res = requests.get(
          'https://apis.cativalab.digital/tenant/v1/auth/me',
          headers={
              'Authorization': f"Bearer {os.environ['CATIVA_API_KEY']}"
          }
      )
      me = res.json()
      ```

      ```csharp C# theme={null}
      using var http = new HttpClient();
      http.DefaultRequestHeaders.Authorization =
          new AuthenticationHeaderValue("Bearer", apiKey);
      var res = await http.GetAsync("https://apis.cativalab.digital/tenant/v1/auth/me");
      var json = await res.Content.ReadAsStringAsync();
      ```
    </CodeGroup>

    A resposta inclui o `id` do usuário associado à chave, `email`, `displayName`, `role`, o nome do `customer` (tenant) e o token efetivo da sessão. Use esse retorno como sanity check de que sua chave está válida e apontando pro tenant certo.

    <Note>
      O tenant é resolvido automaticamente a partir da chave — não é preciso enviar header adicional. Cada API Key pertence a um único tenant; toda chamada autenticada já chega com o contexto correto.
    </Note>
  </Step>

  <Step title="Pronto!">
    A partir daqui você consegue chamar os demais endpoints autenticados da API com a mesma `Authorization: Bearer cativa_live_...`.

    <Note>
      O catálogo público de endpoints da API (incluindo criação de usuário, atribuição de badge e leitura de comunidades/posts) será publicado em breve nesta documentação. Por enquanto, alinhe os endpoints específicos com o time da Cativa via [dev@cativa.digital](mailto:dev@cativa.digital).
    </Note>
  </Step>
</Steps>

## Boas práticas

<AccordionGroup>
  <Accordion title="Não commite chaves">
    Use variáveis de ambiente (ex: `CATIVA_API_KEY`) ou cofres de secrets (Doppler, 1Password Secrets, AWS Secrets Manager). Nunca commite chaves no repositório.
  </Accordion>

  <Accordion title="Nomeie suas chaves">
    Use nomes descritivos (`Sync HubSpot prod`, `CI build`, `Migração 2026-Q2`) — facilita auditar e revogar a correta quando precisar.
  </Accordion>

  <Accordion title="Rotacione periodicamente">
    Recomendamos rotação a cada 90 dias. Se uma chave vazar, revogue imediatamente no Console e gere outra.
  </Accordion>

  <Accordion title="Trate erros">
    `401 Unauthorized` significa que a credencial é inválida ou foi revogada. `403 Forbidden` indica chave válida sem permissão para o recurso. Sempre logue o `traceId` retornado no corpo da resposta de erro.
  </Accordion>
</AccordionGroup>