# Autenticação

> Index of the TerraLab docs for agents: [llms.txt](https://terra-lab.ai/docs/llms.txt). Every docs page is also served as markdown: add .md to its URL.

Toda chamada exige uma conta TerraLab, exceto os dois documentos públicos: [`/v1/openapi.json`](https://mcp.terra-lab.ai/v1/openapi.json) e [`/v1/meta/pricing`](https://mcp.terra-lab.ai/v1/meta/pricing). Há duas formas de se identificar: uma chave de API para código, OAuth 2.1 para agentes.

## Chaves de API

Use uma chave em scripts, back ends e notebooks, em qualquer lugar que não consiga abrir um navegador para entrar.

1. Entre em [terra-lab.ai/login](https://terra-lab.ai/pt-BR/login).
2. Abra [Dashboard, MCP](https://terra-lab.ai/pt-BR/dashboard/mcp), depois **Advanced**, **API keys**.
3. Dê um nome à chave, aceite os termos da API e clique em **Create key**.
4. Copie-a na hora. Uma chave começa com `tlk_`, seguido de 48 caracteres hexadecimais, e é mostrada uma única vez: a TerraLab guarda um hash, nunca a chave.

Envie-a no cabeçalho `Authorization`:

```bash
curl https://mcp.terra-lab.ai/v1/me \
  -H "Authorization: Bearer $TERRALAB_API_KEY"
```

As chaves não expiram, e uma conta pode ter até 20 chaves ativas. Use **Revoke** na mesma página quando uma chave vazar ou um projeto terminar: a próxima chamada com ela responde `401`. As chamadas feitas com uma chave contam na conta que a criou.

Mantenha as chaves fora do controle de versão, do código de front-end e de capturas de tela. Leia-as de uma variável de ambiente ou de um gerenciador de segredos.

## OAuth 2.1 para agentes

Agentes de IA entram em vez de usar uma chave. Quando um agente chama `https://mcp.terra-lab.ai/mcp` pela primeira vez sem token, o servidor responde `401` com um cabeçalho `WWW-Authenticate` que aponta para seus metadados, e o agente abre o login da TerraLab no seu navegador. Você aprova uma vez; o agente passa então a ter um token.

| O quê | Valor |
| --- | --- |
| Metadados do recurso protegido | `https://mcp.terra-lab.ai/.well-known/oauth-protected-resource` |
| Servidor de autorização | `https://terra-lab.ai` |
| Metadados do servidor | `https://terra-lab.ai/.well-known/oauth-authorization-server` |
| Grant | Authorization code com PKCE (`S256`), clientes públicos |
| Registro de cliente | Registro dinâmico, ou um documento de metadados de client ID |
| Escopo | `data` |
| Validade do access token | 1 hora, renovado com um refresh token válido por 30 dias |

A maioria dos agentes cuida de tudo isso sozinha: você só cola a URL do servidor. Veja [Servidor MCP](https://terra-lab.ai/pt-BR/docs/mcp).

Um access token OAuth também funciona na REST API, como Bearer token no mesmo cabeçalho.

## Desconectar um agente

[Dashboard, MCP](https://terra-lab.ai/pt-BR/dashboard/mcp) lista seus **Connected apps**. **Disconnect** revoga o acesso daquele app: a próxima chamada dele responde `401` com `access_revoked`.

Source: https://terra-lab.ai/pt-BR/docs/authentication · Updated 2026-10-27