Ir para o conteúdo

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:

HTTP
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.

ScopeO que ele abre
readLer o corpus e o workspace: fontes, itens, temas, sinais, entidades, boards, tabelas, pipeline do Upwork.
exploreLer ao vivo a web, as redes sociais, os registros e os arquivos. Consome créditos do workspace.
writeEscrever no workspace: boards, tabelas, entidades acompanhadas, contratos de monitoramento, perfil, rascunhos do Upwork.
actAgir sobre o monitoramento: assinar ou cancelar uma fonte, definir uma regra de sinal, iniciar uma investigação, acompanhar uma campanha.
agentsFazer 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 chaveValor padrãoQuando excedido
Requisições por minuto120429 rate_limited, com Retry-After
Turnos de agente por minuto10429 rate_limited, com Retry-After
Requisições por dia20.000429 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.

Uma dúvida sobre a API, ou um erro nesta página? Escreva para nós.