Primeiros passos
Autenticação
Como uma chave identifica um workspace, o que ela permite e como protegê-la.
Uma chave identifica um workspace e um membro, e traz a lista do que ela pode fazer. Esta página explica como enviá-la, o que ela permite, seus limites e como protegê-la.
Enviar a chave#
Toda rota espera a chave no cabeçalho Authorization, exceto GET/api/v1 e GET/api/v1/openapi.json, que são públicas:
Authorization: Bearer piq_live_…O cabeçalho x-api-key: piq_live_… é aceito para clientes que não conseguem definir Authorization.
Uma chave começa com piq_live_, seguido de 38 caracteres. As configurações mostram os 6 primeiros caracteres depois do prefixo, para que você a reconheça. O resto nunca é exibido de novo.
O que uma chave representa#
Uma chave age em nome do membro que a criou, no workspace dele, com o papel dele. As regras do painel se aplicam sem alteração: uma chave nunca vê outro workspace e deixa de funcionar quando seu criador sai do workspace.
Apenas owners e admins criam chaves, em Configurações → API e MCP. Um workspace tem no máximo 25 chaves ativas.
Scopes#
Um scope abre uma família de ferramentas. Cada ferramenta exige o seu, indicado no catálogo.
| Scope | O que ele abre |
|---|---|
read | Ler o corpus e o workspace: fontes, itens, temas, sinais, entidades, boards, tabelas, pipeline do Upwork. |
explore | Ler ao vivo a web, as redes sociais, os registros e os arquivos. Consome créditos do workspace. |
write | Escrever no workspace: boards, tabelas, entidades acompanhadas, contratos de monitoramento, perfil, rascunhos do Upwork. |
act | Agir sobre o monitoramento: assinar ou cancelar uma fonte, definir uma regra de sinal, iniciar uma investigação, acompanhar uma campanha. |
agents | Fazer os agentes Piqline, Requête, Facebook, LinkedIn, Upwork e onboarding responderem. Consome créditos do workspace. |
Escolha o mínimo. read basta para ler o corpus; adicione agents para que um agente responda. Um agente executado com a sua chave só usa as ferramentas que a própria chave poderia chamar.
Validade e revogação#
Uma chave pode nunca expirar, ou expirar em 90 dias ou em um ano. Para revogá-la, abra Configurações → API e MCP, clique em Revogar e depois em Revogar chave. As chamadas que a usam recebem um 401 em até um minuto.
Limites#
| Limite por chave | Valor padrão | Quando excedido |
|---|---|---|
| Requisições por minuto | 120 | 429 rate_limited, com Retry-After |
| Turnos de agente por minuto | 10 | 429 rate_limited, com Retry-After |
| Requisições por dia | 20.000 | 429 quota_exceeded |
Toda resposta traz RateLimit-Limit (a rajada permitida por minuto) e RateLimit-Remaining (o que resta). O limite por minuto reduz as rajadas: ele se aplica por instância de servidor e pode deixar passar um pouco mais que o valor indicado. GET/api/v1/workspace devolve os limites da chave e o número de requisições feitas hoje.
Uso e histórico#
Configurações → API e MCP mostra os últimos 30 dias de uso por ferramenta e por agente, e o histórico de cada requisição: hora, operação, status, duração, erro, trecho da entrada, cliente e rede de origem. O histórico é mantido por 30 dias.
Ele não contém nem a chave nem o corpo completo da requisição: o trecho da entrada é cortado em 300 caracteres, os campos que parecem segredos (password, token, key) são mascarados, e só o prefixo de rede (/24 em IPv4, /48 em IPv6) é guardado, nunca o endereço IP completo.
Proteger uma chave#
- Guarde-a em um gerenciador de segredos ou em uma variável de ambiente. Nunca em um repositório, em uma página web ou em um aplicativo móvel.
- Crie uma chave por uso (um script, um agente, um colega) e dê a ela um nome que você reconheça: você pode revogar uma sem tocar nas outras.
- Dê uma validade às chaves de teste.
- Revogue de imediato uma chave exposta. O Piqline guarda apenas a impressão digital dela: não pode devolvê-la a você, só criar uma nova.
- Uma chave mantém os direitos do seu criador e para de funcionar se ele deixar a equipe. Para um uso duradouro, crie-a a partir de uma conta dedicada à integração.