Get started
Authentication
Every call needs a TerraLab account, except the two public documents: /v1/openapi.json and /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.
- Sign in at terra-lab.ai/login.
- Open Dashboard, MCP, then Advanced, API keys.
- Name the key, accept the API terms and click Create key.
- 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:
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.
An OAuth access token also works on the REST API, as a Bearer token in the same header.
Disconnect an agent
Dashboard, MCP lists your Connected apps. Disconnect revokes that app's access: its next call answers 401 with access_revoked.
Updated 2026-10-27