# Autenticação

> Como uma chave identifica um workspace, o que ela permite e como protegê-la.

Source: https://piqline.com/pt/docs/api/authentication

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](/settings/api). 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](/pt/docs/api/tools#catalogo).

| 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](/settings/api), 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.
