# Authentication

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

Every call needs a TerraLab account, except the two public documents: [`/v1/openapi.json`](https://mcp.terra-lab.ai/v1/openapi.json) and [`/v1/meta/pricing`](https://mcp.terra-lab.ai/v1/meta/pricing). There are two ways to send it: an API key for code, OAuth 2.1 for agents.

## API keys

Use a key for scripts, back ends and notebooks, anything that cannot open a browser to sign in.

1. Sign in at [terra-lab.ai/login](https://terra-lab.ai/login).
2. Open [Dashboard, MCP](https://terra-lab.ai/dashboard/mcp), then **Advanced**, **API keys**.
3. Name the key, accept the API terms and click **Create key**.
4. Copy it at once. A key starts with `tlk_`, followed by 48 hexadecimal characters, and is shown only once: TerraLab stores a hash, never the key.

Send it in the `Authorization` header:

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

Keys do not expire, and an account holds up to 20 live keys. **Revoke** one from the same page when it leaks or a project ends: the next call with it answers `401`. Calls made with a key count against the account that created it.

Keep keys out of source control, front-end code and screenshots. Read them from an environment variable or a secret manager.

## OAuth 2.1 for agents

AI agents sign in instead of using a key. When an agent first calls `https://mcp.terra-lab.ai/mcp` without a token, the server answers `401` with a `WWW-Authenticate` header that points to its metadata, and the agent opens the TerraLab sign-in in your browser. You approve once; the agent then holds a token.

| What | Value |
| --- | --- |
| Protected resource metadata | `https://mcp.terra-lab.ai/.well-known/oauth-protected-resource` |
| Authorization server | `https://terra-lab.ai` |
| Server metadata | `https://terra-lab.ai/.well-known/oauth-authorization-server` |
| Grant | Authorization code with PKCE (`S256`), public clients |
| Client registration | Dynamic registration, or a client ID metadata document |
| Scope | `data` |
| Access token lifetime | 1 hour, renewed with a refresh token valid 30 days |

Most agents handle all of this themselves: you only paste the server URL. See [MCP server](https://terra-lab.ai/docs/mcp).

An OAuth access token also works on the REST API, as a Bearer token in the same header.

## Disconnect an agent

[Dashboard, MCP](https://terra-lab.ai/dashboard/mcp) lists your **Connected apps**. **Disconnect** revokes that app's access: its next call answers `401` with `access_revoked`.

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