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

# Tokens de API

> Crie e gerencie tokens de API para acesso programático à ZeroPath

<h2 id="overview">
  Visão Geral
</h2>

Os tokens de API permitem acessar a API da ZeroPath de forma programática — a partir de pipelines de CI/CD, da CLI, da extensão para VS Code, do servidor MCP ou de integrações personalizadas.

<h2 id="creating-tokens">
  Criando Tokens
</h2>

1. Acesse **Settings → API Tokens** no painel da ZeroPath ([zeropath.com/app/settings/api](https://zeropath.com/app/settings/api)).
2. Clique em **"Create Token"**.
3. Informe um **nome** (opcional, para identificação).
4. Defina uma **expiração** (1–365 dias, padrão: 30 dias).
5. Clique em **Create**.
6. **Copie o Token Secret imediatamente** — ele é exibido apenas uma vez e não pode ser recuperado depois.

Você receberá dois valores:

* **Token ID** — um UUID que identifica o token (seguro para registrar em logs).
* **Token Secret** — a chave secreta (trate como uma senha).

<h2 id="authentication-headers">
  Cabeçalhos de Autenticação
</h2>

Toda requisição à API deve incluir os dois cabeçalhos:

```bash theme={null}
X-ZeroPath-API-Token-Id: <your-token-id>
X-ZeroPath-API-Token-Secret: <your-token-secret>
```

<h3 id="example">
  Exemplo
</h3>

```bash theme={null}
curl -X POST https://zeropath.com/api/v2/vulnerabilities/search \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: your-token-id" \
  -H "X-ZeroPath-API-Token-Secret: your-token-secret" \
  -d '{"query": "SQL injection in API endpoints"}'
```

<h2 id="supported-api-surfaces">
  Superfícies de API Suportadas
</h2>

Os tokens de API autenticam requisições tanto para a API V1 quanto para a API V2 da ZeroPath. A API V2 oferece cobertura ampliada, incluindo:

* **Vulnerabilidades** — liste, pesquise e gerencie descobertas de segurança, incluindo metadados de remediação e de patch quando disponíveis. Quando um issue do Jira está vinculado a uma descoberta, a resposta da API inclui o título do issue do Jira junto ao ID e à URL do issue já existentes. Você pode filtrar a lista de issues por veredicto de validação em runtime para restringir os resultados a issues com desfechos de validação específicos. Quando um issue foi marcado manualmente como não explorável, a resposta inclui um campo `nonExploitableReason` contendo a justificativa humana da triagem (distinta do `validationSecurityAssessment` gerado pelo sistema). Os metadados de status de patch agora incluem o `stage` da geração atual, permitindo acompanhar o progresso do patch em tempo real. Você pode recuperar todas as justificativas humanas de triagem registradas nas descobertas de um repositório — incluindo falsos positivos, veredictos de não explorável, verdadeiros positivos e mudanças de severidade — com um campo `disposition` por entrada indicando a ação de triagem. Você pode atualizar notas de usuário de texto livre em issues individuais (compartilhadas na organização, até 5.000 caracteres; enviar um valor vazio ou apenas com espaços em branco limpa a nota). Você também pode regenerar patches para issues — e, se um issue tiver sido marcado como não corrigível, pode passar `force=true` para sobrescrever essa marcação e solicitar uma nova tentativa de patch. Você pode atualizar a *classificação* de severidade de um issue por rótulo (por exemplo, rebaixar um "High" para "Medium") — a plataforma ajusta a pontuação de severidade subjacente para cair na faixa solicitada. Evidências entre repositórios são incluídas nos detalhes do issue quando o scanner identifica código relacionado em múltiplos repositórios, dando visibilidade completa de cadeias de vulnerabilidade multi-repositório. Você pode excluir branches específicos de repositórios dos resultados da lista de issues usando filtros `excludedRepositoryBranches`
* **SCA** — liste vulnerabilidades de dependências com severidade, dados de alcançabilidade e metadados de status de patch quando existe uma remediação. Você pode filtrar alertas e vulnerabilidades de SCA apenas para aqueles associados a aplicações expostas pelo Wiz. Os avisos de SCA agora incluem campos de inteligência de exploração — status no CISA KEV (`isKnownExploited`, `kevDateAdded`, `kevKnownRansomware`) e pontuações FIRST EPSS (`epssScore`, `epssPercentile`) — para que você possa priorizar com base em dados de exploração no mundo real. Você pode listar avisos de cobertura de resolução de dependências para identificar manifestos em que a árvore de dependências não pôde ser totalmente resolvida, e consultar a cobertura de resolução por ecossistema para quantificar o quão completa é sua verificação de dependências entre os repositórios
* **Relatórios** — gere relatórios de segurança nos formatos DOCX, CSV, SARIF ou SBOM. Se a geração do relatório falhar, o status do relatório é atualizado para `failed` com uma mensagem de erro descrevendo o que deu errado
* **Relatórios Personalizados** — crie, liste e exclua configurações de filtros salvas, recupere estatísticas agregadas (distribuição de severidade, principais classes de vulnerabilidade, MTTR, tendências) e descubra os campos de filtro disponíveis por meio do endpoint de schema de filtros
* **Endpoints** — busca semântica em endpoints e manipuladores de dados detectados
* **Agente** — gerencie gatilhos de eventos, patches, pull requests, instruções globais do agente, histórico de gatilhos, streaming de jobs em tempo real via SSE e playbooks (ative, pause e desinstale fluxos de automação de segurança pré-construídos de uma biblioteca de templates). Os templates de playbook suportam tipos de parâmetro ricos, incluindo texto, número, alternadores booleanos e menus de seleção, dando controle refinado ao ativar fluxos de trabalho. Operações somente leitura — incluindo listar gatilhos de eventos, instâncias de playbook e histórico de gatilhos, recuperar um evento de gatilho específico e ler as instruções globais — exigem apenas a permissão **Agent View**; você não precisa de **Agent Run** para consultar esses recursos. Conversas e jobs do agente são delimitados pelo controle de acesso no nível de repositório — se uma conversa está vinculada a um repositório, apenas usuários com acesso de visualização a esse repositório podem listar, ler, enviar mensagens ou arquivar a conversa. Perder o acesso ao repositório oculta automaticamente essas conversas e jobs de todos os endpoints do agente
* **Verificações de Código Sob Demanda Beta** — envie diffs, arquivos e trechos de código para revisão de segurança assíncrona a partir de CLIs, IDEs, hooks de pre-commit e integrações personalizadas
* **Pacotes de Regras** — navegue por conjuntos curados de templates de regras SAST em linguagem natural cobrindo conformidade, privacidade, logging e mais; habilite ou desabilite templates individuais ou pacotes inteiros para sua organização
* **Regras Personalizadas** — crie, atualize e liste regras de segurança em linguagem natural. As regras podem ter escopo de todos os repositórios (padrão), de repositórios específicos ou por tag — passe `tagIds` sem `repositoryIds` para restringir uma regra aos repositórios que carregam essas tags. A resposta de cada regra inclui um campo `scope` (`allRepositories`, `repositories` ou `tags`) para que você veja como ela é aplicada
* **Organizações** — gerencie organizações, liste/convide/remova membros e atualize os papéis dos membros. Ao convidar um novo membro, você pode opcionalmente especificar um papel (`ADMIN` ou `MEMBER`); o padrão é `MEMBER`, e convidar como `ADMIN` exige permissão de nível administrador. A lista de membros retorna um status claro para cada membro — `active`, `pendingInvite` ou `scimDeprovisioned` — para que você distinga membros ativos de convidados pendentes e de usuários desprovisionados pelo provedor de identidade. A remoção de um membro funciona para membros ativos e para convidados pendentes ou expirados (o convite pendente é revogado automaticamente); administradores ativos não podem ser removidos diretamente — rebaixe-os para membro comum primeiro. Membros desprovisionados via SCIM devem ser gerenciados pelo seu provedor de identidade. Reconvidar um endereço de e-mail que já tem um convite pendente ou expirado revoga automaticamente o convite antigo e envia um novo. O status de sincronização de times do GitHub inclui um timestamp `lastTeamSyncAt` mostrando quando a sincronização mais recente foi concluída, e você pode disparar uma sincronização imediata sob demanda via API ou pelo painel
* **Repositórios** — liste, adicione por URL (repositórios públicos), exclua e gerencie configurações de repositório. As respostas de repositório incluem configuração específica de cada VCS para GitHub, GitLab, Bitbucket, Azure DevOps e repositórios Git genéricos, permitindo identificar o provedor de origem e o status de conexão de cada repositório. Para configurações de monorepo, você pode excluir atomicamente todas as partições de um monorepo em uma única operação, e repositórios excluídos anteriormente podem ser reimportados sem problemas. Tags podem ser marcadas como **padrão** (`isDefault: true`) para que sejam aplicadas automaticamente a todo repositório recém-adicionado, garantindo etiquetagem consistente e acesso de time desde o momento em que um repositório é importado
* **Verificação de Contêineres** — envie imagens de contêiner para verificação de vulnerabilidades por referência de registro ou fazendo upload de um arquivo de imagem (para ambientes isolados). Você pode listar e recuperar imagens de contêiner monitoradas, ver resultados de verificação com atribuição por camada e recomendações de atualização da imagem base, listar descobertas de vulnerabilidade agrupadas por pacote com CVEs agregadas e gerenciar agendamentos de monitoramento recorrente via expressões cron. O resumo do painel de contêineres fornece estatísticas de toda a organização, incluindo contagens de imagens, descobertas por severidade e as principais oportunidades de atualização de imagem base. Você pode vincular imagens a repositórios, excluir imagens monitoradas e verificar se a verificação de contêineres está habilitada para sua organização
* **Verificações** — dispare verificações completas, cancele verificações em execução e gerencie agendamentos de verificação baseados em cron com direcionamento por branch. As respostas de verificação incluem identificadores de repositório para todos os provedores de VCS suportados (GitHub, GitLab, Bitbucket e Azure DevOps). Você pode verificar todos os repositórios conectados a um VCS de uma vez passando `allRepositories: true`, opcionalmente excluindo repositórios específicos com `excludedRepositoryIds`. Você pode filtrar a lista de verificações por nível de severidade (Critical, High, Medium, Low) e agrupar verificações de PR por pull request para ver apenas a verificação mais recente por PR junto a uma contagem de reverificações relacionadas. Se uma verificação completa já estiver em andamento para o mesmo repositório e branch, a API retorna um erro em vez de iniciar uma verificação duplicada. Ao reverificar um PR, a flag `force` agora executa uma verificação completa em vez de uma atualização incremental
* **Times** — crie times, gerencie associações, configure permissões granulares de organização/repositório/time e gerencie templates de permissão padrão que podem ser aplicados a todos os times ou a times específicos da sua organização. O acesso a repositórios pode ser concedido globalmente (todos os repositórios), por repositório ou por tag — concessões baseadas em tag cobrem automaticamente todo repositório que pertence à tag, de modo que o acesso permanece em sincronia à medida que repositórios são adicionados ou removidos. Atualizar ou excluir uma tag que possui concessões de permissão de time exige a permissão TEAM\_MANAGE, e os IDs de repositório fornecidos ao criar ou atualizar uma tag são validados como pertencentes à sua organização. Ao ler as permissões de um time, a resposta inclui um campo estruturado `repoAccess` que indica explicitamente o modo de acesso (`universal` ou `selected`) junto às permissões efetivas, aos IDs de repositório e aos IDs de tag. A permissão **Agent Run** inclui implicitamente **Agent View** — conceder a um time a capacidade de executar o agente concede automaticamente o acesso de visualização também, então você não precisa atribuir as duas permissões separadamente
* **Fontes Personalizadas** — crie, liste, atualize, alterne e exclua declarações personalizadas de fontes de segurança que informam ao scanner sobre pontos de entrada de dados não confiáveis adicionais no seu código
* **Sinks Personalizados** — crie, liste, atualize, alterne e exclua declarações personalizadas de sinks de segurança que informam ao scanner sobre operações sensíveis à segurança adicionais no seu código
* **Pacotes de Fontes Personalizadas** — navegue por conjuntos curados de templates de declaração de fontes, habilite ou desabilite templates individuais ou pacotes inteiros
* **Pacotes de Sinks Personalizados** — navegue por conjuntos curados de templates de declaração de sinks, habilite ou desabilite templates individuais ou pacotes inteiros
* **Integrações** — leia dados de integrações de terceiros, como o Wiz CSPM, incluindo recuperar as configurações do Wiz, listar projetos do Wiz e pesquisar ativos de nuvem e exposições de rede do Wiz
* **Configurações do Scanner** — configure módulos de verificação, limiares de confiança, correção automática (auto-patching) e padrões de arquivos a ignorar no escopo de organização, repositório ou aplicação. Os módulos de verificação habilitados agora incluem `CONTAINER` junto a SAST, IAC, SECRETS, EOL, SCA e AI. O canal de lançamento (release track) para verificações completas e de PR aceita `STABLE` além de `EDGE`. A configuração `allowPrCheckBypass` controla se contribuidores podem ignorar o status do check de PR da ZeroPath sem desabilitar a verificação de PR por completo
* **Estatísticas** — recupere contagens agregadas de issues e atividade de verificação por escopo, incluindo um detalhamento de issues por aplicação com contagens de abertos e resolvidos por repositório. Os endpoints de estatísticas do painel aceitam filtros opcionais de aplicação para restringir os resultados a aplicações específicas dentro dos repositórios. O resumo de postura de segurança inclui uma contagem `reachableExploitableIssues` junto às contagens por nível de severidade já existentes

Para a lista completa de endpoints disponíveis, consulte a [Referência da API](/api-reference/introduction).

<h2 id="token-scopes">
  Escopos de Token
</h2>

Os tokens têm **escopo de organização**. Um token criado em uma organização específica concede acesso a todos os recursos dessa organização, sujeito às mesmas permissões do usuário que o criou.

Não há seleção de escopo refinada no momento da criação do token — o token herda as permissões do usuário criador na organização.

<h2 id="managing-tokens">
  Gerenciando Tokens
</h2>

Na página de configurações API Tokens, você pode:

* **Visualizar** todos os tokens ativos com seus nomes, datas de criação e datas de expiração.
* **Excluir** tokens que não são mais necessários ou que possam estar comprometidos.

Os tokens não podem ser editados após a criação. Para alterar a expiração ou o nome de um token, exclua-o e crie um novo.

<h2 id="token-lifecycle">
  Ciclo de Vida do Token
</h2>

* Os tokens têm uma data de expiração fixa definida na criação (1–365 dias).
* **Tokens expirados são rejeitados automaticamente** — não há renovação automática.
* Quando um token expira, crie um novo e atualize suas integrações.
* Os segredos dos tokens passam por hash criptográfico antes do armazenamento — a ZeroPath nunca armazena o segredo em texto puro.

<h2 id="best-practices">
  Boas Práticas
</h2>

1. **Use nomes descritivos** — nomeie os tokens de acordo com sua finalidade (por exemplo, "CI/CD Pipeline", "VS Code Extension", "MCP Server").
2. **Defina expirações curtas** — use a menor expiração viável para o seu caso de uso.
3. **Faça rotação regularmente** — crie novos tokens e desative os antigos de forma programada.
4. **Nunca faça commit de tokens no controle de versão** — use variáveis de ambiente ou um gerenciador de segredos.
5. **Um token por integração** — evite compartilhar um único token entre múltiplos sistemas para poder revogá-los individualmente.
6. **Exclua tokens comprometidos imediatamente** — se um token pode ter sido exposto, exclua-o e crie um substituto.