認証

API トークンを発行して各ツールに登録する方法

Queria の公開データは認証なしで読めます。API トークンを登録すると、レートリミットの上限が上がり、自分の非公開データセットも読めるようになります。トークンの取得方法は 2 つあります:

queria login — ブラウザ承認だけでトークンを取得・保存する（個人のマシンではこちらが第一の方法）
queria.io の API トークン画面で手動発行 — CI や BI ツールなど非対話環境向け（手動発行トークンは無期限）

API トークン画面は queria.io/settings/tokens です。

いずれの方法でも、トークンの発行には queria.io のアカウントが必要です。アカウント作成は現在招待制です。

Queria CLI

個人のマシンでは queria login を実行します。ブラウザで承認ページが開き、「承認する」を押すとトークンが ~/.config/queria/config.toml に自動保存されます:

queria login    # ブラウザ承認でトークンを取得・保存
queria logout   # 保存したトークンを削除

トークンの有効期限は 90 日です。期限が切れたら queria login を再実行してください。SSH などブラウザを開けない環境では queria login --no-browser を使い、表示された URL を任意の端末のブラウザで承認して、ページに表示されるコードを CLI に貼り付けます。

手動発行したトークンは queria auth で登録します:

queria auth set-token <token>   # ~/.config/queria/config.toml に保存（パーミッション 600）
queria auth status              # トークンの有無と取得元を確認
queria auth clear               # 保存したトークンを削除

トークンは次の優先順で解決されます:

--token オプション
環境変数 QUERIA_TOKEN
設定ファイル ~/.config/queria/config.toml（XDG_CONFIG_HOME を尊重）の token キー

登録したトークンは data.queria.io へのリクエストに Authorization ヘッダとして自動的に付与されます。

Python API

queria.connect() に token を渡します。Python API は環境変数や設定ファイルを自動では読みません:

import queria

with queria.connect(token="YOUR_TOKEN") as conn:
    conn.sql("SELECT * FROM calendar.main.mart_calendar LIMIT 10").show()

MCP サーバー

MCP サーバーは CLI と同じトークン解決（環境変数 QUERIA_TOKEN → 設定ファイル）を使います。queria auth set-token <token> で保存しておくか、MCP クライアントの設定で環境変数 QUERIA_TOKEN を渡してください。

素の DuckDB から使う

DuckDB の HTTP secret としてトークンを登録すると、ATTACH 経由の全リクエスト（カタログファイル・Parquet）に Authorization ヘッダが付きます。ATTACH の前に実行してください:

CREATE SECRET queria_auth (
    TYPE http,
    BEARER_TOKEN 'YOUR_TOKEN',
    SCOPE 'https://data.queria.io'
);

データを変えるトークン

読み取りとデータの変更では必要な権限が違います。データセットの作成・アップロード・公開範囲の変更・削除と、ページの作成・編集・削除には「データセットとページの変更を許可する」を有効にしたトークンが要ります。外して発行したトークンは読み取りだけに使えます。

queria login の承認画面では既定で有効です。個人のマシンから公開するなら、追加の設定は要りません。API トークン画面での手動発行は CI や BI ツール向けで既定が無効なので、データを変えるトークンは発行時に有効にしてください。

権限の足りないトークンでリクエストを送ると、403 と足りない権限の名前が返ります。queria push なら credentials:mint、queria create や queria delete なら datasets:write、ページの作成・編集・削除なら pages:write です。

個人のトークンは、あなたが所属するアカウント（個人・組織）のデータセットに届きます。組織のデータだけを更新するトークンが要るときは、次のサービストークンを使ってください。

組織のサービストークン

組織アカウントとしてデータを更新するためのトークンです。発行と失効は queria.io/accounts/<ハンドル>/settings/tokens で行い、開けるのは組織の管理者だけです。

そのアカウントとして振る舞い、他のアカウント（発行した人の個人アカウントを含む）には届きません
queria create で --owner を省略したときの作成先は、その組織アカウントになります
発行した人が組織を抜けても止まりません。CI で毎日更新するような使い方を、担当者の異動から切り離すためのものです
発行時に表示される値はその場限りです。画面を閉じると二度と表示できません

発行時の「データセットとページの変更を許可する」は既定で有効です。組織のデータを更新することがこのトークンの用途だからです。

トークンを無効にしたときの反映

queria logout や API トークン画面での削除でトークンを無効にすると、反映までに最大 60 秒かかります。 それまでは無効にしたトークンでリクエストが通ることがあります。

トークンが漏れた可能性があるなど、この 60 秒を待てない場合は、トークンを削除したうえで 60 秒のあいだリクエストが通りうる前提で対処してください。 即時に遮断する手段は用意していません。