ObjectOSAPI アクセス
統合のために生成される REST API、認証、API キーについて。
API アクセス
アーティファクトで宣言されたすべてのオブジェクトは、生成された REST API を通じて公開されます。同じエンドポイントが UI、統合、顧客の ETL スクリプトを支えており、別途維持すべき「統合用 API」は存在しません。
ベース URL
https://<project-domain>/api/v1主なエンドポイント:
| Path | 用途 |
|---|---|
/api/v1/data/<object> | 各オブジェクトに対して生成される CRUD（例: /api/v1/data/account） |
/api/v1/data/<object>/{id} | 単一レコードの読み取り／更新／削除 |
/api/v1/actions/<object>/<action> | 宣言的アクションの呼び出し（POST） |
/api/v1/auth/* | 認証（サインイン、セッション、OAuth、OIDC） |
/api/v1/meta/* | 有効化されている場合のメタデータ API（オブジェクト、フィールド、ビュー） |
/api/v1/keys | 呼び出しユーザー向けに一度だけ表示される sys_api_key を発行（POST） |
/api/v1/mcp | OS_MCP_SERVER_ENABLED=true のとき、Streamable HTTP 経由の Model Context Protocol サーバー |
/api/v1/health | 死活／準備状態のプローブ（認証不要） |
プレフィックスのデフォルトは /api/v1（API の basePath である /api と
version である v1 の組み合わせ）で、ObjectOS スタック上で構成可能です。
公開範囲の制御
API の公開はゲートウェイではなく、アーティファクト内のオブジェクト単位で制御されます:
- オブジェクトに
apiEnabled: falseを設定すると、REST 表面から完全に外れます （そのルートは 404 になります）。 apiMethodsホワイトリスト（例:['get', 'list']）を設定すると、オブジェクトを 読み取り専用にしたり、到達可能な操作を制限したりできます。
どちらも REST レイヤーで強制適用されます。 REST API → API 表面の制限 を参照してください。
認証オプション
呼び出し元は次の 3 つの方法で認証できます:
| 方法 | 適した用途 | やり方 |
|---|---|---|
| セッション Cookie | ブラウザ／UI のトラフィック | /api/v1/auth/* を通じてサインインします。Cookie はプロジェクトのホスト名にスコープされます |
| Bearer アクセストークン | モバイル、SPA、短命のサーバージョブ | /api/v1/auth/sign-in/email で資格情報を交換し、Authorization: Bearer <token> を渡します |
| API キー | サーバー間連携、ETL、長期間の統合 | sys_api_key を作成し、bearer トークンとして渡します |
3 つの方法はいずれも同じ AuthPlugin を通過し、SecurityPlugin が権限と
レコードアクセスに対して評価する sys_user コンテキストに解決されます。
API キー
API キーはファーストクラスの sys_api_key レコードです。キーの値自体は
ハッシュ化して保存され、クエリ可能なのは prefix とメタデータのみです。
そのため、漏洩したキーをデータベースから復元することはできません。
キーは次の 2 つの方法で発行できます:
-
Console — 管理者として Console → API Keys にサインインし、所有 ユーザーを選択し、必要に応じて有効期限を設定して、表示されたシークレットを 一度だけコピーします。
-
セルフサービスエンドポイント —
POST /api/v1/keysは認証済みの呼び出し元 に対してキーを発行し、生のシークレットをちょうど一度だけ返します。キーは 呼び出し元自身のユーザーに固定されるため、別の ID へのなりすましには使用 できません:curl -X POST https://app.example.com/api/v1/keys \ -H "Authorization: Bearer <session-or-access-token>" \ -H "Content-Type: application/json" \ -d '{"name": "etl-pipeline"}' # → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" }
以降のリクエストでは、キーを bearer トークン、x-api-key ヘッダー、または
Authorization: ApiKey として渡します。REST のデータ／メタデータ API はいずれも
MCP と同じ検証器で認証し、キー所有者の権限とレコードレベルセキュリティの下で
実行されます:
curl https://app.example.com/api/v1/data/account \
-H "x-api-key: os_pk_live_…"キーを失効させるには、対応する sys_api_key レコードに対して
revoke_api_key アクションを実行します（Console UI でも利用可能）。
失効は次のリクエストから即座に有効になります。
ページネーション、フィルタリング、ソート
生成されるリストエンドポイントは、標準の ObjectStack クエリパラメーターを受け付けます:
| パラメーター | 意味 |
|---|---|
?limit= | ページサイズ（サーバー側の上限が適用されます） |
?offset= または ?cursor= | ページネーション |
?filter= | ObjectQL のフィルター構文を使用したサーバー側フィルタリング |
?sort= | ソート式（例: -created_at） |
?fields= | スパースなフィールド選択 |
完全なフィルター文法についてはフレームワークのドキュメントを参照してください。 ランタイムの文法が信頼できる情報源です。
レート制限
フレームワークの RateLimiter プリミティブ（または ingress / API
ゲートウェイ）を使用して、IP ごと・アイデンティティごとの制限を適用します。
推奨される初期バケットは 本番環境への準備
に記載されています。
CORS
呼び出し元が異なるオリジンのブラウザで動作する場合は、ingress または ランタイムのミドルウェアで CORS を構成します。ワイルドカードオリジンと 資格情報付きリクエストを組み合わせないでください。
OpenAPI / ディスカバリー
該当する機能がイメージに含まれている場合、ランタイムは生成された REST API の OpenAPI ドキュメントを提供できます。オブジェクト名や生成されたルートは デプロイされたアーティファクトに従うため、顧客の統合では URL を手作業で 組み立てるのではなく、デプロイごとの OpenAPI ドキュメントからクライアントを 生成してください。