> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 公開 API、キー、webhook

顧客が構築するためのバージョン管理された REST サーフェス。

## 始める前に

[ファイル] → [フォルダーを開く] を使用して、Visual Studio Code でダウンロードした supastack プロジェクトを開き、[ターミナル] → [新しいターミナル] を選択します。リポジトリ ルートは、package.json、アプリ、およびパッケージを含むフォルダーです。そこで以下のコマンドを実行し、ターミナルを開いたままにしておきます。コマンドが認識されない場合は、続行する前にツールのインストール ガイドを完了してください。

まずプラットフォームのチュートリアルをお読みください。サーバーは、ブラウザまたは電話のリクエストに応答するアプリ プロセスです。 Web は apps/web/.env.local を読み取り、Expo は apps/mobile/.env.local を読み取り、データベース移行コマンドは root .env を読み取ります。データベースなしの /dashboard デモは、Postgres の移行が必要な実際の /auth アカウントとは別のものです。電話またはデスクトップのみのチェックアウトには、別途実行される Web バックエンドが必要です。

[ツールをインストールしてコードを取得](https://supastack.dev/ja/docs/web/before-you-start.md)

[コマンド、ファイル、設定を学ぶ](https://supastack.dev/ja/docs/web/terminal-basics.md)

[Web の初回実行チュートリアルを完了する](https://supastack.dev/ja/docs/web/ship-in-5-minutes.md)

```
corepack pnpm --filter @supastack/web dev
```


## インストールとセットアップ

packages/api がバージョン管理されたコントラクトを定義します: 各リクエストとレスポンスの zod スキーマ、エラーエンベロープ、/api/v1/openapi で配信され /api/docs で描画される OpenAPI ドキュメント。ワークスペース API キーは設定 → 開発者で作成します。平文は一度だけ表示され、その後はハッシュ化されたキーのみが残ります。

キーはプレフィックス付き(sk_<env>_…)、スコープ付き(デフォルトは読み取り)で、リクエストごとにワークスペースへ解決されます。送信 webhook サブスクリプションは同じ開発者サーフェスで管理します。

```
GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…
```


## 実装ワークフロー

Bearer キーで認証します。サーバーはクライアント提供の id ではなくキーからワークスペースを解決します。レスポンス形状はバージョン管理を維持 — v1 内では追加的変更、破壊的変更は新バージョンの後ろに。

送信 webhook ではエンドポイント URL をイベントカタログにサブスクライブします。配信は署名・記録され、利用者は検証とリプレイが可能です。カタログには webhook-events.ts、試行には webhook-delivery.ts を使います。


## 検証とトラブルシューティング

失効したキーが 401 を返すこと、スコープ不足のキーが拒否されること、OpenAPI ドキュメントがパースできることを確認します。webhook では署名検証、失敗後の再配信、イベントペイロードがプロバイダーシークレットを含まないことをテストしてください。


## 次へ

[ファイルストレージ](https://supastack.dev/ja/docs/web/storage.md)