スタート

認証

1 つのヘッダー、1 つのキー、1 つのアカウント。キーとは何か、どこに置けるか、どう拒否されるか。

ヘッダー

/v1 へのすべてのリクエストはキーをベアラートークンとして送ります。

curl 'https://api.immit.co/v1/me' \
  -H "Authorization: Bearer $IMMIT_API_KEY"

/v1 ではセッションクッキーも immit のアカウントトークンも拒否されます。認証するのはキーだけで、キーが認証するのはそれだけです。キーを持つアカウントのページ、設定、フラッシュカードには一切届きません。

キーとは

キーは開発者アカウント上の資格情報で、それ以上のものではありません。ティア、クォータ、バーストはアカウントのもので、そのすべてのキーで共有されます。2 つのアプリが 2 つのキーを使っても、ティアが売るものを分け合います。キーを保持するものの数だけキーを作り、それぞれにその名前を付け、使わなくなったものは無効化してください。

キーは ik_live_ で始まり、URL セーフな 43 文字が続きます。コンソールには先頭 12 文字が表示され、キーを見分けるには十分です。テストモードのキーはありません。無料ティアがサンドボックスです。

キーのローテーション

新しいキーを作り、クライアントを移してから古いキーを無効化します。サブスクリプションはキーではなくアカウントに結びついているので、無効化がプランに触れることはありません。無効化したキーは行と使用量をコンソールに残し、履歴が途切れません。

キーを置ける場所

サーバー、CLI、ワーカー、あなたのマシンで動くエージェント。/v1 は Authorization ヘッダーを許可した状態でどのオリジンにも応答するため、ページから直接呼ぶこともできます。それこそが、ページに置いたキーは漏れたキーだという理由です。

キーをブラウザやクライアントアプリケーションに含めて配布しないでください。自分のサーバーを経由して呼び出してください。オリジン制限付きの公開キーは後の形であり、今の形ではありません。

キーが拒否されるとき

ステータス	コード	いつ
401	`unauthorized`	ベアラーがまったくないか、ベアラーがキーではない。
401	`api_key_invalid`	形式は正しい `ik_live_` のベアラーだが、immit が発行したものではない。タイプミスは汎用の 401 ではなくこれになります。
401	`api_key_revoked`	キーがコンソールから無効化された。
401	`api_key_suspended`	immit の担当者がメールの後にキーを停止した。

401 · application/json

{
  "errors": [
    {
      "code": "api_key_revoked",
      "detail": "The API key is revoked"
    }
  ]
}

キーを確かめる

GET /v1/me はキーの名前、アカウントのティアとクォータ、今日の使用量を返します。デプロイスクリプトから呼ぶのに向いた呼び出しで、他と同じように数えられます。