Autenticazione

Ogni chiamata richiede un account TerraLab, tranne i due documenti pubblici: /v1/openapi.json e /v1/meta/pricing. Ci sono due modi per inviarlo: una chiave API per il codice, OAuth 2.1 per gli agenti.

Chiavi API

Usa una chiave per script, back end e notebook, ovvero tutto ciò che non può aprire un browser per accedere.

1. Accedi su terra-lab.ai/login.
2. Apri Dashboard, MCP, poi Advanced, API keys.
3. Dai un nome alla chiave, accetta i termini dell'API e clicca Create key.
4. Copiala subito. Una chiave inizia con tlk_, seguito da 48 caratteri esadecimali, e viene mostrata una sola volta: TerraLab conserva un hash, mai la chiave.

Inviala nell'header Authorization:

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

Le chiavi non scadono e un account può avere fino a 20 chiavi attive. Usa Revoke dalla stessa pagina quando una chiave viene divulgata o un progetto finisce: la chiamata successiva con quella chiave risponde 401. Le chiamate fatte con una chiave vengono conteggiate sull'account che l'ha creata.

Tieni le chiavi fuori dal controllo di versione, dal codice front-end e dagli screenshot. Leggile da una variabile d'ambiente o da un gestore di segreti.

OAuth 2.1 per gli agenti

Gli agenti AI accedono invece di usare una chiave. Quando un agente chiama per la prima volta https://mcp.terra-lab.ai/mcp senza token, il server risponde 401 con un header WWW-Authenticate che punta ai suoi metadati, e l'agente apre l'accesso TerraLab nel tuo browser. Approvi una volta sola; l'agente poi possiede un token.

La maggior parte degli agenti gestisce tutto da sé: devi solo incollare l'URL del server. Vedi Server MCP.

Un access token OAuth funziona anche con l'API REST, come Bearer token nello stesso header.

Scollegare un agente

Dashboard, MCP elenca le tue Connected apps. Disconnect revoca l'accesso di quell'app: la sua chiamata successiva risponde 401 con access_revoked.