認証

公開されている 2 つのドキュメント、/v1/openapi.json と /v1/meta/pricing を除き、すべての呼び出しに TerraLab アカウントが必要です。認証の方法は 2 つあります。コード向けの API キーと、エージェント向けの OAuth 2.1 です。

API キー

スクリプト、バックエンド、ノートブックなど、ブラウザーを開いてサインインできない環境ではキーを使います。

1. terra-lab.ai/login でサインインします。
2. ダッシュボード、MCP を開き、Advanced、API keys の順に進みます。
3. キーに名前を付け、API 利用規約に同意して、Create key をクリックします。
4. すぐにコピーしてください。キーは tlk_ で始まり、その後に 48 文字の 16 進数が続きます。表示は 1 回だけです。TerraLab が保存するのはハッシュであり、キーそのものは保存しません。

キーは Authorization ヘッダーで送ります。

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

キーに有効期限はなく、1 つのアカウントで最大 20 個の有効なキーを持てます。キーが漏れたときやプロジェクトが終わったときは、同じページで Revoke をクリックしてください。そのキーでの次の呼び出しは 401 を返します。キーでの呼び出しは、そのキーを作成したアカウントの利用分として数えられます。

キーは、ソース管理、フロントエンドのコード、スクリーンショットに含めないでください。環境変数またはシークレットマネージャーから読み込んでください。

エージェント向けの OAuth 2.1

AI エージェントはキーを使わず、サインインします。エージェントが token なしで https://mcp.terra-lab.ai/mcp を初めて呼び出すと、サーバーは 401 と、メタデータを指す WWW-Authenticate ヘッダーを返します。エージェントはブラウザーで TerraLab のサインイン画面を開きます。承認は 1 回だけで、その後エージェントが token を保持します。

ほとんどのエージェントは、これらをすべて自動で処理します。サーバーの URL を貼り付けるだけです。MCP サーバーをご覧ください。

OAuth のアクセス token は REST API でも使えます。同じヘッダーに Bearer token として入れてください。

エージェントの接続を解除する

ダッシュボード、MCP に Connected apps の一覧があります。Disconnect をクリックすると、そのアプリのアクセスが取り消されます。そのアプリの次の呼び出しは、access_revoked とともに 401 を返します。