認証

Suede Search API は ベアラー API キー で認証する。すべてのリクエストは、Authorization ヘッダーにキーを 携える必要がある。

キーを作成する

キーの作成と管理は、Suede アカウントの 設定 → 連携 → API キー で行う:

1. キーに名前を付け、後で見分けられるようにする。
2. 作成 をクリックする。完全なキーは 一度だけ 表示される ── 直ちにコピーし、安全な場所に保管すること。
3. それ以降は、マスクされた形式(suede_live_abc123…wxyz)しか表示されない。Suede は生のキーを保存しないため、 再び取り出すことはできない。キーを失った場合は、それを失効させて新しいものを作成すること。

キーは同じ画面からいつでも失効させられる。失効したキーは直ちに機能しなくなる。

キーの形式

キーは次のような見た目である:

suede_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

suede_live_ というプレフィックスで始まり、その後にランダムな秘密が続く。キーはパスワードと同じように扱う こと ── それを保持する者は誰でも、あなたのアカウントのクレジットで検索できてしまう。キーはサーバー側に保ち、 クライアント側のコード、モバイルアプリ、公開リポジトリには決して埋め込まないこと。

Authorization ヘッダー

キーは、すべてのリクエストでベアラートークンとして送る:

Authorization: Bearer suede_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

認証付きリクエストを行う

curl "https://api.suede.io/v1/search?q=hello+world" \
  -H "Authorization: Bearer $SUEDE_API_KEY"

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new("Bearer", Environment.GetEnvironmentVariable("SUEDE_API_KEY"));
var json = await http.GetStringAsync("https://api.suede.io/v1/search?q=hello+world");
Console.WriteLine(json);

const res = await fetch("https://api.suede.io/v1/search?q=hello+world", {
  headers: { Authorization: `Bearer ${process.env.SUEDE_API_KEY}` },
});
console.log(await res.json());

スコープ

アカウント設定で作成したキーは search スコープを持ち、これがすべての v1 検索エンドポイントと 使用状況 へのアクセスを与える。必要なスコープを欠くキーで行ったリクエストは、HTTP 403 と type: insufficient_scope で拒否される ── エラー を参照のこと。

認証の失敗

キーが欠落している、不正な形式である、無効である、または失効している場合、HTTP 401 を返す:

{ "error": { "type": "unauthorized", "message": "Provide a valid API key as a Bearer token.", "request_id": "…" } }

次のステップ

• ベース URL(api.suede.io)を使う。
• ウェブ検索 から始める。
• エラー と レート制限 を扱う。