Primeiros passos
Autenticação
Toda chamada exige uma conta TerraLab, exceto os dois documentos públicos: /v1/openapi.json e /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.
- Entre em terra-lab.ai/login.
- Abra Dashboard, MCP, depois Advanced, API keys.
- Dê um nome à chave, aceite os termos da API e clique em Create key.
- 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:
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.
Um access token OAuth também funciona na REST API, como Bearer token no mesmo cabeçalho.
Desconectar um agente
Dashboard, MCP lista seus Connected apps. Disconnect revoga o acesso daquele app: a próxima chamada dele responde 401 com access_revoked.
Atualizado em 2026-10-27