# Autenticazione

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

Ogni chiamata richiede un account TerraLab, tranne i due documenti pubblici: [`/v1/openapi.json`](https://mcp.terra-lab.ai/v1/openapi.json) e [`/v1/meta/pricing`](https://mcp.terra-lab.ai/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](https://terra-lab.ai/it/login).
2. Apri [Dashboard, MCP](https://terra-lab.ai/it/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`:

```bash
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.

| Cosa | Valore |
| --- | --- |
| Metadati della risorsa protetta | `https://mcp.terra-lab.ai/.well-known/oauth-protected-resource` |
| Server di autorizzazione | `https://terra-lab.ai` |
| Metadati del server | `https://terra-lab.ai/.well-known/oauth-authorization-server` |
| Grant | Authorization code con PKCE (`S256`), client pubblici |
| Registrazione del client | Registrazione dinamica, oppure un documento di metadati con l'ID del client |
| Scope | `data` |
| Durata dell'access token | 1 ora, rinnovato con un refresh token valido 30 giorni |

La maggior parte degli agenti gestisce tutto da sé: devi solo incollare l'URL del server. Vedi [Server MCP](https://terra-lab.ai/it/docs/mcp).

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

## Scollegare un agente

[Dashboard, MCP](https://terra-lab.ai/it/dashboard/mcp) elenca le tue **Connected apps**. **Disconnect** revoca l'accesso di quell'app: la sua chiamata successiva risponde `401` con `access_revoked`.

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