# Autenticação com apiKey

> Aprenda a criar sua apiKey, usá-la na URL das chamadas e proteger essa chave como se fosse uma senha.

- URL canônica: https://docs.growthstation.app/docs/api/conceitos/autenticacao
- Idioma: pt-BR
- Última atualização: 2026-09-20T08:21:20.449Z
- Produto: GS Engage
- Mantido por: Produto GS Engage



<PageHero emoji="🔑" title="Autenticação com apiKey" description="Toda chamada à API do GS Engage precisa provar quem você é. Isso é feito com uma chave única — a sua apiKey." gradient="brand" />

🎯 O que você vai conseguir aqui [#-o-que-você-vai-conseguir-aqui]

Você quer que os seus sistemas conversem com o GS Engage — puxar leads, criar prospecções, receber avisos por webhook. Antes de qualquer coisa, a API precisa ter certeza de que é você mesmo do outro lado. Essa "prova de identidade" é a sua **apiKey** (chave de API).

Nesta página você vai entender **o que é essa chave, onde criá-la, como usá-la nas chamadas** e — o mais importante — **como protegê-la** para que ninguém use o seu acesso indevidamente.

<Callout type="info">
  Um lembrete de vocabulário: quando falamos em <TextHighlight>endpoint</TextHighlight>, estamos falando de um endereço da API que executa uma ação (por exemplo, listar leads ou criar uma prospecção). Cada endpoint fica sob a URL base <TextHighlight>[https://api.gsengage.com](https://api.gsengage.com)</TextHighlight>, no caminho <TextHighlight>/api/v1</TextHighlight>.
</Callout>

🗝️ O que é a apiKey [#️-o-que-é-a-apikey]

A apiKey é um texto único (com cerca de 40 caracteres) que representa o seu acesso à API. Pense nela como a **senha da sua integração**: quem tem a chave consegue fazer, em nome da sua empresa, tudo o que a API permite — inclusive **criar e alterar dados de verdade**.

Por isso, a regra número um é simples: **trate a apiKey como uma senha.**

🛠️ Como criar a sua apiKey [#️-como-criar-a-sua-apikey]

A chave é gerada dentro da própria plataforma do GS Engage. Você não precisa abrir chamado nem falar com o suporte.

<Steps>
  <Step num={1} title="Abra as Configurações">
    No GS Engage, acesse o menu <TextHighlight>Configurações</TextHighlight>.
  </Step>

  <Step num={2} title="Entre em Configurações de API">
    Dentro de Configurações, abra a seção <TextHighlight>Configurações de API</TextHighlight>. É ali que ficam as suas chaves.
  </Step>

  <Step num={3} title="Gere e copie a chave">
    Gere a apiKey e **copie na hora**. Guarde em um lugar seguro (veja a seção de segurança abaixo). Ela funciona imediatamente, sem etapa de ativação.
  </Step>
</Steps>

<Callout type="tip" title="Guarde com carinho">
  Copie a chave para um cofre de senhas ou uma variável de ambiente assim que criá-la. É muito mais fácil guardar bem desde o início do que ter que revogar e refazer tudo depois.
</Callout>

🔗 Como usar a chave nas chamadas [#-como-usar-a-chave-nas-chamadas]

No GS Engage, a apiKey vai na **própria URL da requisição**, como um parâmetro chamado `apiKey`. Isso se chama *query param* (parâmetro de consulta) — é aquele pedaço que vem depois do `?` no endereço.

<Callout type="warning" title="Não é um header">
  Diferente de muitas APIs, aqui a chave **não** vai em um cabeçalho (header) `Authorization`. Ela vai na URL, no formato `?apiKey=SUA_CHAVE`. Se você tentar mandar por header, a API vai responder que você não está autenticado.
</Callout>

O formato é sempre este:

```
https://api.gsengage.com/api/v1/CAMINHO?apiKey=SUA_CHAVE
```

Vamos ver um exemplo real. Para listar os seus leads, o gatilho é uma chamada `GET` ao endpoint de leads, com a sua chave na URL:

<Tabs items={['curl', 'JavaScript', 'Python']}>
  <Tab value="curl">
    ```bash
    curl "https://api.gsengage.com/api/v1/leads?apiKey=$GSENGAGE_API_KEY"
    ```
  </Tab>

  <Tab value="JavaScript">
    ```js
    const apiKey = process.env.GSENGAGE_API_KEY;

    const resposta = await fetch(
      `https://api.gsengage.com/api/v1/leads?apiKey=${apiKey}`
    );
    const leads = await resposta.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os
    import requests

    api_key = os.environ["GSENGAGE_API_KEY"]

    resposta = requests.get(
        "https://api.gsengage.com/api/v1/leads",
        params={"apiKey": api_key},
    )
    leads = resposta.json()
    ```
  </Tab>
</Tabs>

Se a chave estiver correta, você recebe um `200` (sucesso) com a sua lista de leads. Na prática, isso significa que a integração está autenticada e pronta para trabalhar. Se a chave estiver ausente ou errada, você recebe um `401 Unauthorized` — a API está dizendo "não sei quem é você".

<Callout type="info" title="Precisa combinar mais parâmetros?">
  Quando o endpoint aceitar filtros ou paginação (como `page`, `limit` ou `search`), você simplesmente encadeia os parâmetros com `&`. Exemplo: `?apiKey=SUA_CHAVE&limit=50&page=2`.
</Callout>

✅ Confirme que a sua chave funciona [#-confirme-que-a-sua-chave-funciona]

Antes de sair integrando, vale um teste rápido e **inofensivo** só para confirmar que a chave está valendo. Use o endpoint de campos personalizados: ele é leve, é **somente leitura** e exige apiKey.

O gatilho:

```bash
curl "https://api.gsengage.com/api/v1/custom-fields?apiKey=$GSENGAGE_API_KEY"
```

Um `200` com uma lista confirma que está tudo certo. A resposta pode até vir vazia (`[]`) se o seu projeto ainda não tiver campos personalizados — e tudo bem, isso continua significando que **a chave funciona**. O que importa aqui é o `200`, não o conteúdo.

<Callout type="tip" title="Por que esse endpoint?">
  Escolhemos `GET /api/v1/custom-fields` de propósito: ele só lê dados e não altera nada. É o jeito mais seguro de validar a chave sem risco de mexer na sua operação.
</Callout>

🚨 Segurança: a chave vai na URL — cuidado redobrado [#-segurança-a-chave-vai-na-url--cuidado-redobrado]

<Callout type="danger" title="Sua apiKey pode vazar sem você perceber">
  Como a apiKey viaja **dentro da URL**, ela acaba sendo **registrada e copiada em vários lugares** que você talvez nem imagine:

  * **Logs de servidor** — a URL completa (com a chave) costuma ser gravada nos registros de acesso de servidores, proxies e balanceadores.
  * **Histórico do navegador** — se a URL for aberta em um navegador, a chave fica salva no histórico.
  * **Links compartilhados** — ao colar uma URL de exemplo num chat, e-mail, ticket, print ou documento, você está compartilhando a chave junto.
  * **Ferramentas de monitoramento e analytics** — muitas capturam a URL inteira das requisições.

  Qualquer pessoa com uma dessas cópias da chave pode agir **em nome da sua empresa**, inclusive **alterar dados reais**.

  **Boas práticas obrigatórias:**

  1. **Trate como senha.** Nunca digite a chave "na mão" dentro de código, prints ou mensagens.
  2. **Use variável de ambiente.** Guarde a chave numa variável (como `GSENGAGE_API_KEY`) e leia dela no código — foi o que fizemos em todos os exemplos acima.
  3. **Nunca suba a chave para um repositório**, especialmente se for público. Adicione o arquivo de configuração (por exemplo, `.env`) ao seu `.gitignore`.
  4. **Não cole a chave em canais públicos** — grupos, fóruns, issues abertas, prints em redes sociais.
  5. **Se desconfiar que vazou, revogue na hora.** Volte em <TextHighlight>Configurações → Configurações de API</TextHighlight>, revogue a chave comprometida e gere uma nova. É rápido e corta o acesso indevido imediatamente.
</Callout>

Bons e maus usos na prática [#bons-e-maus-usos-na-prática]

<DoDont>
  <DoDontItem type="do">
    Ler a chave de uma variável de ambiente (

    `GSENGAGE_API_KEY`

    ) e montá-la na URL só na hora da chamada.
  </DoDontItem>

  <DoDontItem type="dont">
    Escrever a chave direto no código-fonte (

    `?apiKey=ab12cd34...`

    ) e commitar no Git.
  </DoDontItem>

  <DoDontItem type="do">
    Guardar a chave num cofre de senhas ou no gerenciador de secrets da sua infraestrutura.
  </DoDontItem>

  <DoDontItem type="dont">
    Colar uma URL de exemplo com a chave real em um chamado de suporte, chat ou print de tela.
  </DoDontItem>

  <DoDontItem type="do">
    Manter o arquivo 

    `.env`

     no 

    `.gitignore`

     para ele nunca ir parar no repositório.
  </DoDontItem>

  <DoDontItem type="dont">
    Subir a chave para um repositório público "só pra testar rápido".
  </DoDontItem>

  <DoDontItem type="do">
    Revogar e regerar a chave imediatamente ao menor sinal de vazamento.
  </DoDontItem>

  <DoDontItem type="dont">
    Continuar usando uma chave que você suspeita ter exposto, na esperança de que ninguém tenha visto.
  </DoDontItem>
</DoDont>

⚠️ Não existe ambiente de teste: toda chamada é real [#️-não-existe-ambiente-de-teste-toda-chamada-é-real]

Este é o ponto mais importante para você não ter sustos.

<Callout type="danger" title="Não há sandbox — os dados são de produção">
  O GS Engage **não tem um ambiente de teste separado** nem uma "chave de teste". Existe **uma única API, com dados reais**.

  Isso significa que **toda chamada afeta a sua operação de verdade**: um `POST` de lead cria um lead que aparece para o seu time; uma prospecção iniciada entra na fila do vendedor; um webhook criado começa a disparar.

  Como se proteger enquanto experimenta:

  * **Comece pelas leituras.** Use endpoints `GET` (como `/api/v1/custom-fields` e `/api/v1/leads`) para explorar — eles não mudam nada.
  * **Só faça escrita quando tiver certeza.** Antes de qualquer `POST`, `PATCH`, `PUT` ou `DELETE`, confirme os dados. Um lead criado via API, por exemplo, entra marcado como <TextHighlight>Levantada de Mão</TextHighlight> e vai direto para o topo da fila de atividades do vendedor.
</Callout>

<Callout type="tip" title="Dica de quem já passou por isso">
  Ao construir uma integração nova, deixe as ações de escrita comentadas ou atrás de uma confirmação até validar o fluxo inteiro só com leituras. Assim você entende o comportamento da API sem gerar ruído na operação do time.
</Callout>

❓ Perguntas frequentes [#-perguntas-frequentes]

<FAQ>
  <FAQItem question="Recebi 401 Unauthorized. O que houve?">
    O `401` significa que a API não reconheceu a sua chave — ela está **ausente, incorreta ou foi revogada**. Confira se você incluiu `?apiKey=SUA_CHAVE` na URL, se a chave foi copiada por inteiro (sem espaços ou quebras) e se ela ainda está ativa em <TextHighlight>Configurações → Configurações de API</TextHighlight>. As mensagens de erro do GS Engage já vêm em português para facilitar o diagnóstico.
  </FAQItem>

  <FAQItem question="Posso mandar a apiKey no header Authorization?">
    Não. No GS Engage a autenticação é feita **exclusivamente pelo query param** `?apiKey=SUA_CHAVE` na URL. Enviar por header não autentica a chamada.
  </FAQItem>

  <FAQItem question="A chave expira sozinha?">
    A chave continua válida até você revogá-la. Se ela vazar ou você não precisar mais dela, revogue e gere uma nova em Configurações de API.
  </FAQItem>

  <FAQItem question="Preciso saber programar para usar a API?">
    Não necessariamente. O GS Engage expõe gatilhos nativos no **Zapier** (por exemplo, gatilhos de webhook), o que permite montar integrações sem escrever código. Ferramentas como **Make** e **n8n** também conseguem consumir a API REST e receber webhooks.
  </FAQItem>
</FAQ>

📚 Continue por aqui [#-continue-por-aqui]

Artigos Relacionados [#artigos-relacionados]

<RelatedArticles>
  <RelatedArticle href="/docs/api/comece-aqui/quickstart" title="Primeira chamada à API" description="Faça sua primeira requisição do zero, passo a passo." />

  <RelatedArticle href="/docs/api/conceitos/limites-de-uso" title="Limites de uso (rate limit)" description="Quantas chamadas por minuto você pode fazer e como tratar o 429." />

  <RelatedArticle href="/docs/api/conceitos/respostas-e-erros" title="Entendendo os erros" description="O que significam 400, 401, 404 e 429 e como corrigir cada um." />

  <RelatedArticle href="/docs/api/conceitos/paginacao-filtros-ordenacao" title="Paginação e ordenação" description="Como percorrer listas grandes com limit, page, orderBy e orderDirection." />
</RelatedArticles>