Skip to main content
Square Cloud API へのすべてのリクエストには API キーを付けます。キーはアカウントのセキュリティ設定で作成します。1 つのアカウントで名前付きのキーを最大 10 個まで保持でき、新しいキーのシークレットは一度しか表示されません。ここで作成したキーに有効期限はありません。CLI と VS Code 拡張機能が接続時に受け取るキーは 90 日間有効です。

​
キーの送信

キーは Authorization ヘッダーで送信します。Bearer プレフィックスは任意です。
キーはサーバー上の環境変数に保管してください。キーを持っている人は誰でも、そのスコープの範囲内であなたのアカウントを操作できます。API の利用は利用規約および利用許諾ポリシーの対象となります。
型付きのクライアントを使いたい場合は、JavaScript、Python、Go 向けの Square Cloud SDK がキーを送信し、このリファレンスのすべてのエンドポイントをラップします。

​
スコープ

各キーはスコープを持ち、スコープによってキーでできることが決まります。フルアクセスのキーは、後から追加されるものを含むすべてのスコープをカバーします。キーのスコープ外のエンドポイントを呼び出すと 403 MISSING_SCOPE が返されます。既存のキーのスコープは編集できないため、必要なスコープを持つ新しいキーを作成してください。 各エンドポイントのページにも、Authorization フィールドのすぐ下に必要なスコープが記載されています。
名前から想像されるより広い範囲に及ぶスコープもあります。files:write と apps:deploy はアプリケーション内で任意のコードを実行でき、snapshots:read は環境変数を含むアプリケーション全体をダウンロードでき、envs:read はアプリケーションのすべてのシークレットを公開し、databases:credentials はデータベースのパスワードを渡します。また、workspaces:manage で付与したアクセス権は、キーを取り消した後も有効なままです。各連携には必要なスコープだけを付与してください。

​
キーをリソースに制限する

キーは最大 30 個のアプリケーションとデータベースに制限することもできます。それ以外のリソースに関する呼び出しや、それらのリソースに絞り込めないアカウント全体のエンドポイントへの呼び出しには 403 RESOURCE_NOT_ALLOWED が返されます。アカウント情報の取得のような一覧系のエンドポイントは、キーの対象となるリソースだけを返します。 保存されたファイルはアプリケーションではなくアカウントに属するため、制限付きのキーには blob:read や blob:write のスコープを付けられません。アプリケーション用のキーと Blob Storage 用のキーを別々に作成してください。

​
エラー

その他のコードはすべてエラーに記載しています。

​
無効なキーへの保護

すべてのアカウントを守るため、どのアカウントにも属さない API キーを送り続ける IP アドレスを API は一時的にブロックし、短時間 429 RATE_LIMITED を返します。通常どおり使われている有効なキーには影響しません。リクエストが 401 を受け取った場合は、ループで再試行せず、キーを修正または交換してください。

​
次のステップ

最初のリクエスト

ベース URL、最初の curl 呼び出し、レスポンスの形式。

制限と制約

プランごとのリクエスト枠とブロックされている地域。