Tessera
ログイン無料で始める
ドキュメント一覧

認証・APIキー

概要

Tesseraには2つの認証方式があります。管理画面（ブラウザ）はセッションCookie、GraphQL APIとMCPサーバーはAPIキー（Authorization: Bearer <キー>）です。GraphQLはこの両方に対応しており、ログイン中のセッションでも、発行済みのAPIキーでも実行できます。

詳細仕様

セッションCookie認証

ログイン時にhttpOnlyのアクセストークン・リフレッシュトークンをCookieとして発行します。JavaScriptからは触れられない設計です。セッション認証でGraphQLを実行する場合、常にワークスペースへのフルアクセス（read_write相当）として扱われ、後述のコンテンツタイプ単位のオーバーライドの対象にもなりません（ログイン中の人間の操作という前提のため）。

APIキー認証

/settings/api-keysから発行します。キーはtsr_live_から始まる形式で、発行直後の画面にのみ平文の値が一度だけ表示されます。以降はDBにハッシュ値のみが保存されるため、再表示はできません（紛失した場合は失効させて再発行してください）。

APIキーには2つのスコープがあります。

  • read_only: コンテンツ・スキーマの読み取りのみ
  • read_write: 上記に加え、コンテンツの作成・更新・アーカイブ、スキーマ変更の提案（propose_content_type_change）が可能

発行フォームのデフォルトはread_onlyです（最小権限をデフォルトにしています）。MCPサーバーでは、read_writeスコープを持たないキーで接続した場合、書き込み系のツール自体がツール一覧に登録されません（AIエージェント側からその存在自体が見えない設計です）。

コンテンツタイプ単位のオーバーライド

キー全体のデフォルトスコープとは別に、特定のコンテンツタイプにだけ異なる実効スコープ（read_only/read_write/none）を割り当てられます。noneはそのコンテンツタイプへのアクセス自体を遮断し、一覧にも表示されなくなります（読み取り専用への降格とは異なる扱いです）。

オーバーライドは発行後も追加・変更・削除が可能です（キー全体のデフォルトスコープ自体は発行後に変更できません。変更したい場合は失効・再発行が必要です）。オーバーライドが権限を緩める方向の変更（none/read_only→read_write）である場合は、確認ダイアログの表示と監査ログの記録が必須です。権限を狭める変更には確認ダイアログはありません。

失効・再発行

失効は取り消し不可の操作で、revokedAtが設定されます（レコード自体は監査目的で残ります）。失効後はGraphQL・MCP接続とも即座に認証エラーになります。lastUsedAtは読み取り専用の呼び出しも含め、認証成功のたびに更新されます。

エラーケース

認証情報がない、または無効（失効済み・存在しないキー、セッション切れ）

401 Unauthorized

MCP・GraphQLとも{ "error": "unauthorized" }相当のレスポンスです。

認証は成功しているがスコープが不足している場合

403相当 / FORBIDDEN

GraphQLはFORBIDDEN拡張コード付きのGraphQLエラーです。例えばread_onlyキーでGraphQL Mutationを実行しようとすると、「コンテンツタイプ "articles" への書き込み権限がありません」という内容のエラーになります。MCPの書き込み系ツールの場合は{ status: "permission_denied", ... }という形でツール応答内に含まれます（HTTPレベルでは200扱いで、MCPプロトコルの応答本文としてエラーを表現します）。

コンテンツタイプ単位のオーバーライドでnoneが設定されている場合

そのコンテンツタイプは一覧（list_content_types等）から存在ごと除外され、個別アクセスも権限不足として扱われます。

関連ドキュメント