Uma Factorial IT API key autentica as chamadas que você faz para a Factorial IT API, uma API REST. Crie uma quando quiser uma integração ou script para ler ou alterar seus dados através da API.
Funcionalidade
Visão Geral
As chaves autenticam solicitações para a Factorial IT API (REST). Existem dois tipos, cada um com seu próprio alcance:
- Chave API da Empresa. Limitada a uma empresa. Ela abre todos os endpoints que funcionam em recursos a nível de empresa: dispositivos, funcionários, acessórios, ingressos, SaaS e mais.
- Chave API do Espaço de Trabalho. Cobre todo o seu espaço de trabalho. Ela abre os endpoints a nível de espaço de trabalho, por exemplo, listando e visualizando as empresas em seu espaço de trabalho.
A maioria dos endpoints precisa de uma Chave API da Empresa. Apenas os endpoints do espaço de trabalho (sob /workspace/) precisam de uma Chave API do Espaço de Trabalho. A referência da API mostra um distintivo em cada endpoint com o tipo que espera.
Como usar: criar uma Chave API da Empresa
- Vá para Configurações > Desenvolvedores.
- Clique em Criar chave.
- Digite um Nome da chave de 4 caracteres ou mais, por exemplo "Minha integração".
- Defina o Nível de Acesso como Apenas leitura ou Leitura/escrita.
- Se desejar, defina uma Expiração (dias). Deixe em branco para uma chave que nunca expira.
- Clique em Criar chave, depois em Copiar segredo. O segredo é mostrado apenas uma vez.
Mantenha a chave em um lugar seguro. Qualquer pessoa que a tiver pode acessar seus dados através da API.
Usar a chave
Envie a chave no cabeçalho Authorization de cada solicitação:
curl https://api.getFactorial IT.com/v1/devices \
-H "Authorization: Bearer YOUR_API_KEY"
Revogar uma chave
- Vá para Configurações > Desenvolvedores e encontre a chave sob Factorial IT API keys.
- Abra o menu ⋯ na sua linha e clique em Revogar.
- Confirme.
A chave para de funcionar imediatamente e não pode ser recuperada. Chaves revogadas permanecem na lista para que você possa rastreá-las. Para remover uma permanentemente, abra seu menu ⋯ e clique em Excluir.
Visualizar logs da API
Depois que sua empresa enviar sua primeira solicitação, um cartão Ver logs da API aparece na aba Desenvolvedores. Clique nele para abrir logs da API. A página lista as últimas 50 solicitações REST e MCP para sua empresa. A coluna Ator mostra a chave, cliente MCP ou funcionário por trás de cada uma.
Dicas e Melhores Práticas
- Escolha Apenas leitura, a menos que a integração precise escrever. Dê a cada chave o nível de acesso mais baixo que funcione.
- Defina uma expiração para integrações temporárias. Uma chave que nunca expira continua sendo um risco até que alguém a revogue.
- Copie o segredo imediatamente. Ele não será mostrado novamente.
- Use uma chave por integração. Um nome claro informa o que para de funcionar quando você a revoga.
- Verifique os logs da API. A coluna Ator mostra quem está chamando a API.
Solução de Problemas e FAQ
Solução de Problemas
-
Um endpoint do espaço de trabalho rejeita sua chave. Endpoints sob
/workspace/precisam de uma Chave API do Espaço de Trabalho, não de uma Chave API da Empresa. - Um endpoint da empresa rejeita sua chave. A maioria dos endpoints precisa de uma Chave API da Empresa. Verifique o distintivo no endpoint na referência da API.
- Uma solicitação de escrita falha. A chave pode ser Apenas leitura. Crie uma chave com acesso Leitura/escrita.
- Uma integração parou de funcionar. A chave pode ter sido revogada ou atingido sua expiração. Crie uma nova chave.
- Você não vê o cartão Ver logs da API. Ele aparece apenas depois que sua empresa fez pelo menos uma solicitação.
FAQ
-
Posso ver o segredo novamente após criar a chave?
Não. Ele é mostrado apenas uma vez. Se você perder, crie uma nova chave.
-
Posso restaurar uma chave revogada?
Não. Ela para de funcionar imediatamente e não pode ser restaurada.
-
Por que as chaves revogadas ainda estão listadas?
Para rastreabilidade. Use Excluir no menu ⋯ para remover uma permanentemente.
-
Quantas solicitações os logs da API mostram?
As 50 solicitações REST e MCP mais recentes para sua empresa.