リファレンス

APIリファレンスと統合のヒント。

概要

リファレンス

CommonRockは認証・セッション・簡易DBを提供し、アプリ側のサーバ実装を最小化します。

アクセストークン + リフレッシュトークンを含むエンドユーザ認証

Custom DB スロットによる簡易ストレージ

IP制限・レート制限付きのサーバ間イントロスペクション

プロジェクト専用のAPIベースパス

認証方式

CommonRockのAPIは2つの認証方式をサポートしています。エンドポイントによって、片方または両方の方式で呼び出せます。

公開クライアント

ブラウザやモバイルアプリから直接呼び出す場合に使用します。

必要なヘッダ

X-Client-Id: pk_live_***

X-Client-Key: pk_live_***

Origin: https://app.example.com

パスに /public/ が含まれます

サーバ

バックエンドサーバから呼び出す場合に使用します。

必要なヘッダ

X-API-Key: sk_live_***

シークレットキーは絶対にクライアントに公開しない

公開クライアントのスコープ

各公開クライアントには一連のスコープが付与されます。匿名呼び出しとエンドユーザ認証済み呼び出しで異なるスコープ集合を設定できます。付与外のスコープの呼び出しは 403 client_scope_denied を返します。

スコープ	許可される操作
end_users:signup	新規エンドユーザを登録（サインアップ）します。
end_users:login	エンドユーザをログインさせ、トークンを発行します。
end_users:refresh	エンドユーザのリフレッシュトークンをローテーションします。
end_users:logout	現在のエンドユーザセッションを失効します。
end_users:me	現在のエンドユーザのプロフィールを読み取ります。
sql:execute	公開 SQL クエリ定義を実行します（同期・非同期）。
tables:rw	公開対応テーブルの行を、エンドユーザにスコープして読み書きします。
relay:proxy	リレー経由でリソースサーバへリクエストをプロキシします。

クイックスタート

バックエンドからOpaqueトークンをイントロスペクトします。

1APIシークレットキーを発行し、サーバで安全に保管します。

2各リクエストでイントロスペクトを呼び、結果を30秒程度キャッシュします。

3拒否イベントを記録して監査可能にします。

クイックスタートコード

curl -X POST /org_demo_payments/v1/sessions/introspect \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_***' \
  -d '{"token":"access_token"}'

フレームワーク連携テンプレート

Next.js / React / iOS / Android / Node.js でログイン〜introspect まで

ブラウザ／ネイティブからは Public Client (X-Client-Id) を、サーバ側からは API Secret Key (X-API-Key) を使います。Public Client で許可する Origin はポータル側で先に設定してください。

// app/api/login/route.ts (Next.js App Router)
// 1. Browser → your Next.js Route Handler
// 2. Route Handler → CommonRock public endpoint with X-Client-Id / X-Client-Key
// 3. Set HttpOnly session cookie back to the browser

import { NextResponse } from "next/server";

const COMMONROCK_BASE = process.env.COMMONROCK_API_BASE_URL!;
const CLIENT_ID = process.env.COMMONROCK_CLIENT_ID!;
const CLIENT_KEY = process.env.COMMONROCK_CLIENT_KEY!;

export async function POST(request: Request) {
  const body = await request.json();
  const res = await fetch(`${COMMONROCK_BASE}/v1/public/end-users/login`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Client-Id": CLIENT_ID,
      "X-Client-Key": CLIENT_KEY,
      Origin: request.headers.get("origin") ?? ""
    },
    body: JSON.stringify(body)
  });
  const payload = await res.json();
  if (!res.ok) return NextResponse.json(payload, { status: res.status });
  const response = NextResponse.json({ ok: true, user: payload.user });
  response.cookies.set("cr_at", payload.access_token, {
    httpOnly: true,
    secure: true,
    sameSite: "strict",
    maxAge: payload.expires_in
  });
  return response;
}

本番では Public Client / API Secret Key を必ず .env など秘匿化された場所に保管してください。

Next.js

Route Handler でサーバ側にキーを置き、HttpOnly Cookie でブラウザに返すパターンを推奨。

iOS / Android

ネイティブアプリは Public Client + 端末情報を Origin として送る運用。Secret Key は埋め込まない。

Node.js / その他バックエンド

サーバ間 API は X-API-Key + allowed_cidrs/allowed_origins で IP 帯を絞ること。

APIリファレンス

エンドポイントをクリックして詳細を表示

公開APIのリクエスト/レスポンス仕様を詳述します。

エンドユーザ管理 · 5 データベース · 3 ユーザデータベース · 8 リレー · 4 認証 · 1

エンドユーザ管理

ユーザ登録・ログイン・セッション管理

5 エンドポイント

POST

エンドユーザ登録

公開サーバ

/:api_base/v1/public/end-users/signup

/:api_base/v1/end-users/signup

外部IDとパスワードで新規登録し、アクセストークンとリフレッシュトークンを発行します。

使用するパス:/:api_base/v1/public/end-users/signup

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

リクエストボディ

フィールド	型	必須	説明
external_id	string	必須	アプリ内ユーザID（最大128バイト。半角英数字なら128文字）
password	string	必須	12文字以上で大文字・小文字・数字を含むこと。よくあるパスワードや漏洩実績のあるパスワードは拒否されます。
device_id	string	任意	最大128文字。body か X-Device-Id ヘッダで必須

リクエスト例

curl -X POST /org_demo_payments/v1/public/end-users/signup \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -d '{"external_id":"user-1","password":"password123","device_id":"iphone-15"}'

レスポンス

レスポンス項目

フィールド	型	必須	説明
token	string	必須	アクセストークン（Opaque）
refresh_token	string	必須	リフレッシュトークン
end_user.id	uuid	必須	エンドユーザID
end_user.external_id	string	必須	外部ID
session_id	uuid	必須	セッションID
expires_at	datetime	必須	アクセストークン有効期限（ISO8601）
refresh_expires_at	datetime	必須	リフレッシュ有効期限（ISO8601）

正常レスポンス例

{
  "token":"access_token",
  "refresh_token":"refresh_token",
  "end_user":{"id":"uuid","external_id":"user-1"},
  "session_id":"uuid",
  "expires_at":"2026-02-04T13:00:00Z",
  "refresh_expires_at":"2026-03-05T13:00:00Z"
}

異常レスポンス例

{
  "code":"external_id_conflict",
  "message":"External ID already registered",
  "detail":{"code":"external_id_conflict","message":"External ID already registered"}
}

エラー

•400 external_id_required

•400 password_too_short / password_no_uppercase / password_no_lowercase / password_no_digit

•400 password_common / password_breached

•400 device_id_required

•409 external_id_conflict

•401 invalid_client_key / invalid_api_key

•403 origin_required / origin_denied

•403 client_scope_denied

補足

💡アクセストークンは Authorization: Bearer で利用します。

💡アクセストークンは既定で24時間、リフレッシュトークンは720時間（30日）有効です。いずれもデプロイ毎に変更可能です。

POST

エンドユーザログイン

公開サーバ

/:api_base/v1/public/end-users/login

/:api_base/v1/end-users/login

外部IDとパスワードでログインし、トークンを再発行します。

使用するパス:/:api_base/v1/public/end-users/login

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

リクエストボディ

フィールド	型	必須	説明
external_id	string	必須	外部ID
password	string	必須	パスワード
device_id	string	任意	最大128文字。body か X-Device-Id ヘッダで必須

リクエスト例

curl -X POST /org_demo_payments/v1/public/end-users/login \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -d '{"external_id":"user-1","password":"password123","device_id":"iphone-15"}'

レスポンス

レスポンス項目

フィールド	型	必須	説明
token	string	必須	アクセストークン
refresh_token	string	必須	リフレッシュトークン
end_user.id	uuid	必須	エンドユーザID
end_user.external_id	string	必須	外部ID
session_id	uuid	必須	セッションID
expires_at	datetime	必須	アクセストークン有効期限
refresh_expires_at	datetime	必須	リフレッシュ有効期限

正常レスポンス例

{
  "token":"access_token",
  "refresh_token":"refresh_token",
  "end_user":{"id":"uuid","external_id":"user-1"},
  "session_id":"uuid",
  "expires_at":"2026-02-04T13:00:00Z",
  "refresh_expires_at":"2026-03-05T13:00:00Z"
}

異常レスポンス例

{
  "code":"invalid_credentials",
  "message":"Invalid credentials",
  "detail":{"code":"invalid_credentials","message":"Invalid credentials"}
}

エラー

•400 device_id_required

•401 invalid_credentials

•403 account_locked

•401 invalid_client_key / invalid_api_key

•403 origin_required / origin_denied

•403 client_scope_denied

補足

💡アクセストークンは既定で24時間、リフレッシュトークンは720時間（30日）有効です。いずれもデプロイ毎に変更可能です。

POST

トークン更新

公開サーバ

/:api_base/v1/public/end-users/refresh

/:api_base/v1/end-users/refresh

リフレッシュトークンでアクセストークンを再発行します。

使用するパス:/:api_base/v1/public/end-users/refresh

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

リクエストボディ

フィールド	型	必須	説明
refresh_token	string	必須	リフレッシュトークン
device_id	string	任意	最大128文字。body か X-Device-Id ヘッダで必須

リクエスト例

curl -X POST /org_demo_payments/v1/public/end-users/refresh \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -d '{"refresh_token":"refresh_token","device_id":"iphone-15"}'

レスポンス

レスポンス項目

フィールド	型	必須	説明
token	string	必須	新しいアクセストークン
refresh_token	string	必須	新しいリフレッシュトークン
end_user.id	uuid	必須	エンドユーザID
end_user.external_id	string	必須	外部ID
session_id	uuid	必須	セッションID
expires_at	datetime	必須	アクセストークン有効期限
refresh_expires_at	datetime	必須	リフレッシュ有効期限

正常レスポンス例

{
  "token":"new_access_token",
  "refresh_token":"new_refresh_token",
  "end_user":{"id":"uuid","external_id":"user-1"},
  "session_id":"uuid",
  "expires_at":"2026-02-04T13:10:00Z",
  "refresh_expires_at":"2026-03-05T13:10:00Z"
}

異常レスポンス例

{
  "code":"invalid_refresh_token",
  "message":"Invalid refresh token",
  "detail":{"code":"invalid_refresh_token","message":"Invalid refresh token"}
}

エラー

•400 refresh_token_required

•400 device_id_required

•401 invalid_refresh_token

•403 account_locked

•401 invalid_client_key / invalid_api_key

•403 origin_required / origin_denied

•403 client_scope_denied

補足

💡リフレッシュトークンは使い捨てです。

💡アクセストークンは既定で24時間、リフレッシュトークンは720時間（30日）有効です。いずれもデプロイ毎に変更可能です。

POST

ログアウト

公開サーバ

/:api_base/v1/public/end-users/logout

/:api_base/v1/end-users/logout

アクセストークンを失効します。

使用するパス:/:api_base/v1/public/end-users/logout

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

Authorization: Bearer <access_token>

リクエスト例

curl -X POST /org_demo_payments/v1/public/end-users/logout \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -H 'Authorization: Bearer access_token'

レスポンス

レスポンス項目

フィールド	型	必須	説明
status	string	必須	ok 固定

正常レスポンス例

{"status":"ok"}

異常レスポンス例

{
  "code":"invalid_session",
  "message":"Invalid session",
  "detail":{"code":"invalid_session","message":"Invalid session"}
}

エラー

•401 invalid_session

•401 invalid_client_key / invalid_api_key

•403 client_scope_denied

GET

セッション中ユーザ取得

公開サーバ

/:api_base/v1/public/end-users/me

/:api_base/v1/end-users/me

アクセストークンに紐づくエンドユーザを取得します。

使用するパス:/:api_base/v1/public/end-users/me

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

Authorization: Bearer <access_token>

リクエスト例

curl /org_demo_payments/v1/public/end-users/me \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -H 'Authorization: Bearer access_token'

レスポンス

レスポンス項目

フィールド	型	必須	説明
id	uuid	必須	エンドユーザID
external_id	string	必須	外部ID

正常レスポンス例

{"id":"uuid","external_id":"user-1"}

異常レスポンス例

{
  "code":"invalid_session",
  "message":"Invalid session",
  "detail":{"code":"invalid_session","message":"Invalid session"}
}

エラー

•401 invalid_session

•401 invalid_client_key / invalid_api_key

•403 client_scope_denied

データベース

SQLクエリ定義の実行（同期・非同期）

3 エンドポイント

POST

SQLクエリ定義実行

公開サーバ

/:api_base/v1/public/sql/execute

/:api_base/v1/sql/execute

登録済みSQLクエリ定義を実行してページング取得します。

使用するパス:/:api_base/v1/public/sql/execute

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

Authorization: Bearer <access_token> (required when template requires access token)

リクエストボディ

フィールド	型	必須	説明
query_definition_id	uuid	必須	SQLクエリ定義ID
params	object	任意	SQLパラメータ。auth. で始まる名前は予約済みのため拒否されます。
limit	int	任意	1〜200（SQL_MAX_ROWS でデプロイ毎に変更可、既定200）
cursor	string	任意	offset or keyset cursor
cursor_mode	string	任意	offset / keyset (default offset)

リクエスト例

curl -X POST /org_demo_payments/v1/public/sql/execute \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -H 'Authorization: Bearer access_token' \
  -d '{"query_definition_id":"uuid","params":{"author_id":"user-1"},"limit":200}'

レスポンス

レスポンス項目

フィールド	型	必須	説明
rows	array	必須	結果行
next_cursor	string	任意	次ページのカーソル
warnings[].code	string	任意	警告コード
warnings[].message	string	任意	警告メッセージ

正常レスポンス例

{"rows":[{"id":"uuid","title":"post-1"}],"next_cursor":"200","warnings":[{"code":"order_by_missing","message":"ORDER BY is missing; pagination may be unstable"}]}

異常レスポンス例

{
  "code":"template_server_only",
  "message":"This template is not available to public clients",
  "detail":{"code":"template_server_only","message":"This template is not available to public clients"}
}

エラー

•401 invalid_client_key / invalid_api_key

•401 authorization_required

•403 template_server_only

•404 template_not_found

•403 origin_required / origin_denied

•403 client_scope_denied

•400 reserved_param

•400 invalid_cursor

補足

💡テンプレートがアクセストークン必須の場合は Authorization ヘッダが必要です。

💡limit は既定200で、SQL_MAX_ROWS（デプロイ毎に変更可、既定200）で上限が決まります。

💡query_definition_id は SQLクエリ定義ID です。

💡書き込みはproject_idが自動注入され、UPDATE/DELETEはWHERE必須。

💡cursor_mode=keysetはORDER BY必須、同一方向のみ、OFFSET不可。

💡keyset cursorはORDER BY値のJSON配列をBase64(URL-safe, paddingなし)で渡します。

💡ORDER BY混在時はoffsetへフォールバック。

💡warnings: order_by_missing / keyset_fallback / keyset_cursor_ignored / keyset_cursor_unavailable

💡公開クライアントは execute_visibility が public のテンプレートのみ実行できます。server_only のテンプレートは 403 template_server_only を返します。

💡requires_access_token のテンプレートをエンドユーザの Bearer トークン無しで呼ぶと 401 authorization_required を返します。

💡予約バインド :auth.end_user_id と :auth.project_id はサーバが注入します。auth. で始まるクライアントパラメータは 400 reserved_param で拒否されます。

POST

SQLクエリ定義実行（非同期）

公開サーバ

/:api_base/v1/public/sql/execute-async

/:api_base/v1/sql/execute-async

SQLクエリ定義をバックグラウンド実行に投入し、結果をポーリングします。

使用するパス:/:api_base/v1/public/sql/execute-async

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

Authorization: Bearer <access_token> (when template requires access token)

リクエストボディ

フィールド	型	必須	説明
query_definition_id	uuid	必須	SQLクエリ定義ID
params	object	任意	SQLパラメータ。auth. で始まる名前は予約済みのため拒否されます。
limit	int	任意	1〜200（SQL_MAX_ROWS でデプロイ毎に変更可、既定200）

リクエスト例

curl -X POST /org_demo_payments/v1/public/sql/execute-async \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -d '{"query_definition_id":"uuid","params":{"author_id":"user-1"}}'

レスポンス

レスポンス項目

フィールド	型	必須	説明
job_id	string	必須	非同期ジョブ ID
status	string	必須	queued / running / succeeded / failed
submitted_at	datetime	必須	ジョブ受理時刻（ISO8601）
expires_at	datetime	必須	ジョブと結果の有効期限（ISO8601）
storage	string	必須	結果の保存先（redis または memory）

正常レスポンス例

{
  "job_id":"uuid",
  "status":"queued",
  "submitted_at":"2026-06-12T01:00:00Z",
  "expires_at":"2026-06-12T01:15:00Z",
  "storage":"redis"
}

エラー

•401 invalid_client_key / invalid_api_key

•401 authorization_required

•403 template_server_only

•404 template_not_found

•403 client_scope_denied

•400 reserved_param

補足

💡公開クライアントは sql:execute スコープが必要です。execute_visibility / アクセストークンの規則は同期版と同じです。

💡ジョブと結果は非同期ジョブ TTL（既定900秒、デプロイ毎に変更可）で失効します。

💡status は queued → running → succeeded | failed と遷移します。成功時は result、失敗時は error が入ります。

💡長時間のレポートには非同期版を、対話的な読み取りには同期版 /sql/execute を使ってください。

GET

SQL 非同期ジョブのステータス

公開サーバ

/:api_base/v1/public/sql/execute-async/{job_id}

/:api_base/v1/sql/execute-async/{job_id}

非同期 SQL ジョブのステータスと（終了時は）結果を取得します。

使用するパス:/:api_base/v1/public/sql/execute-async/{job_id}

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

パスパラメータ

フィールド	型	必須	説明
job_id	string	必須	非同期ジョブ ID

リクエスト例

curl /org_demo_payments/v1/public/sql/execute-async/<job_id> \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***'

レスポンス

レスポンス項目

フィールド	型	必須	説明
job_id	string	必須	非同期ジョブ ID
status	string	必須	queued / running / succeeded / failed
result	object	任意	status が succeeded のときの結果ペイロード
error	object	任意	status が failed のときのエラーエンベロープ
expires_at	datetime	必須	ジョブと結果の有効期限（ISO8601）

正常レスポンス例

{
  "job_id":"uuid",
  "status":"succeeded",
  "result":{"rows":[{"id":"uuid","title":"post-1"}],"next_cursor":null},
  "expires_at":"2026-06-12T01:15:00Z"
}

異常レスポンス例

{
  "code":"async_sql_job_not_found",
  "message":"Async SQL job not found",
  "detail":{"code":"async_sql_job_not_found","message":"Async SQL job not found"}
}

エラー

•404 async_sql_job_not_found

•401 invalid_client_key / invalid_api_key

補足

💡不明・他プロジェクト・失効済みのジョブは 404 async_sql_job_not_found を返します。

ユーザデータベース

スキーマレスなテーブル・カラム・行

8 エンドポイント

POST

テーブル（一覧 / 作成）サーバ専用

/:api_base/v1/tables

プロジェクトのユーザDBテーブルを一覧、または型付きカラムで新規作成します。

リクエスト

ヘッダ

X-API-Key: <raw_api_key>

リクエストボディ

フィールド	型	必須	説明
name	string	必須	テーブル名（小文字・英数字・アンダースコア）
columns	ColumnDefinition[]	必須	カラム定義の配列
columns[].name	string	必須	カラム名
columns[].type	string	必須	text / integer / numeric / boolean / timestamptz / uuid のいずれか
columns[].nullable	boolean	任意	NULL を許可するか（既定 true）
columns[].encrypted	boolean	任意	true の場合、サーバはクライアント側暗号化済みの不透明な暗号文を保存します（既定 false）

リクエスト例

# List tables
curl /org_demo_payments/v1/tables -H 'X-API-Key: sk_live_***'

# Create a table
curl -X POST /org_demo_payments/v1/tables \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_***' \
  -d '{"name":"posts","columns":[{"name":"title","type":"text"},{"name":"likes","type":"integer","nullable":true}]}'

レスポンス

レスポンス項目

フィールド	型	必須	説明
id	uuid	必須	テーブル名（小文字・英数字・アンダースコア）
name	string	必須	テーブル名（小文字・英数字・アンダースコア）
columns	array	必須	カラム定義の配列

正常レスポンス例

{
  "id":"uuid",
  "name":"posts",
  "columns":[
    {"name":"title","type":"text","nullable":true,"encrypted":false},
    {"name":"likes","type":"integer","nullable":true,"encrypted":false}
  ]
}

エラー

•400 bad_request (invalid column type / name, table or column limit reached)

•409 conflict (table already exists)

•401 missing_api_key / invalid_api_key

補足

💡テーブルはプロジェクトあたり最大20、カラムはテーブルあたり最大50です。

💡全テーブルに end_user_id カラムが予約され自動注入されます。カラム一覧には含めません。

💡encrypted カラムはクライアントが渡した不透明な暗号文を保存します。サーバは復号しません。

DELETE

テーブル削除サーバ専用

/:api_base/v1/tables/{table_name}

テーブルと全行を削除します。

リクエスト

ヘッダ

X-API-Key: <raw_api_key>

パスパラメータ

フィールド	型	必須	説明
table_name	string	必須	テーブル名（小文字・英数字・アンダースコア）

リクエスト例

curl -X DELETE /org_demo_payments/v1/tables/posts -H 'X-API-Key: sk_live_***'

レスポンス

正常レスポンス例

{"status":"ok"}

エラー

•404 not_found (table not found)

•401 missing_api_key / invalid_api_key

POST

カラム（追加 / 削除）サーバ専用

/:api_base/v1/tables/{table_name}/columns

テーブルに型付きカラムを追加、または既存カラムを削除します。

リクエスト

ヘッダ

X-API-Key: <raw_api_key>

パスパラメータ

フィールド	型	必須	説明
table_name	string	必須	テーブル名（小文字・英数字・アンダースコア）

リクエストボディ

フィールド	型	必須	説明
name	string	必須	カラム名
type	string	必須	text / integer / numeric / boolean / timestamptz / uuid のいずれか
nullable	boolean	任意	NULL を許可するか（既定 true）
encrypted	boolean	任意	true の場合、サーバはクライアント側暗号化済みの不透明な暗号文を保存します（既定 false）

リクエスト例

# Add a column
curl -X POST /org_demo_payments/v1/tables/posts/columns \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_***' \
  -d '{"name":"body","type":"text","nullable":true}'

# Drop a column
curl -X DELETE /org_demo_payments/v1/tables/posts/columns/body -H 'X-API-Key: sk_live_***'

レスポンス

正常レスポンス例

{"status":"ok"}

エラー

•404 not_found (table or column not found)

•409 conflict (column already exists)

•400 bad_request (column limit reached / invalid type)

•401 missing_api_key / invalid_api_key

補足

💡追加する NOT NULL カラムは既存行と互換である必要があります。

POST

行（一覧 / 作成）サーバ専用

/:api_base/v1/tables/{table_name}/rows

ソート・ページング・カーソルで行を一覧、または新しい行を挿入します。

リクエスト

ヘッダ

X-API-Key: <raw_api_key>

パスパラメータ

フィールド	型	必須	説明
table_name	string	必須	テーブル名（小文字・英数字・アンダースコア）

クエリパラメータ

フィールド	型	必須	説明
sort	string	任意	ソート対象カラム。先頭に - を付けると降順
limit	int	任意	1ページの件数。1〜200（既定50）
cursor	string	任意	前回レスポンスの不透明なページングカーソル

リクエストボディ

フィールド	型	必須	説明
<column>	any	任意	行のカラム名と値のペア

リクエスト例

# List rows (newest first, page of 20)
curl '/org_demo_payments/v1/tables/posts/rows?sort=-created_at&limit=20' \
  -H 'X-API-Key: sk_live_***'

# Insert a row
curl -X POST /org_demo_payments/v1/tables/posts/rows \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_***' \
  -d '{"title":"hello","likes":0}'

レスポンス

レスポンス項目

フィールド	型	必須	説明
rows	array	必須	結果行
next_cursor	string	任意	前回レスポンスの不透明なページングカーソル

正常レスポンス例

{"rows":[{"id":"uuid","title":"hello","likes":0}],"next_cursor":null}

エラー

•404 not_found (table not found)

•400 bad_request (limit out of range / invalid sort)

•401 missing_api_key / invalid_api_key

補足

💡limit は既定50で、1〜200の範囲です。次ページは next_cursor を使います。

💡シークレット経路では end_user_id を直接設定しないでください。サーバが管理します。

PATCH

行（取得 / 更新 / 削除）サーバ専用

/:api_base/v1/tables/{table_name}/rows/{row_id}

ID を指定して1行を取得・部分更新・削除します。

リクエスト

ヘッダ

X-API-Key: <raw_api_key>

パスパラメータ

フィールド	型	必須	説明
table_name	string	必須	テーブル名（小文字・英数字・アンダースコア）
row_id	uuid	必須	行 ID（UUID）

リクエストボディ

フィールド	型	必須	説明
<column>	any	任意	行のカラム名と値のペア

リクエスト例

# Get a row
curl /org_demo_payments/v1/tables/posts/rows/<row_id> -H 'X-API-Key: sk_live_***'

# Update a row
curl -X PATCH /org_demo_payments/v1/tables/posts/rows/<row_id> \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_***' \
  -d '{"likes":5}'

# Delete a row
curl -X DELETE /org_demo_payments/v1/tables/posts/rows/<row_id> -H 'X-API-Key: sk_live_***'

レスポンス

正常レスポンス例

{"id":"uuid","title":"hello","likes":5}

エラー

•404 not_found (table or row not found)

•401 missing_api_key / invalid_api_key

GET

公開テーブル（一覧）公開クライアント

/:api_base/v1/public/tables

現在のエンドユーザ向けに公開対応テーブルを一覧します。

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

Authorization: Bearer <access_token>

リクエスト例

curl /org_demo_payments/v1/public/tables \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -H 'Authorization: Bearer access_token'

レスポンス

正常レスポンス例

{"tables":[{"name":"posts","columns":[{"name":"title","type":"text"}]}]}

エラー

•403 table_not_public

•401 invalid_session

•403 client_scope_denied

補足

💡tables:rw スコープとエンドユーザの Bearer トークンが必要です。

💡公開されていないテーブルは 403 table_not_public を返します。

POST

公開行（一覧 / 作成）公開クライアント

/:api_base/v1/public/tables/{table_name}/rows

現在のエンドユーザにスコープされた行を一覧、または挿入します。

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

Authorization: Bearer <access_token>

パスパラメータ

フィールド	型	必須	説明
table_name	string	必須	テーブル名（小文字・英数字・アンダースコア）

クエリパラメータ

フィールド	型	必須	説明
sort	string	任意	ソート対象カラム。先頭に - を付けると降順
limit	int	任意	1ページの件数。1〜200（既定50）
cursor	string	任意	前回レスポンスの不透明なページングカーソル

リクエストボディ

フィールド	型	必須	説明
<column>	any	任意	行のカラム名と値のペア

リクエスト例

# List the current end user's rows
curl '/org_demo_payments/v1/public/tables/posts/rows?limit=20' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -H 'Authorization: Bearer access_token'

# Insert a row (auto-scoped to the end user)
curl -X POST /org_demo_payments/v1/public/tables/posts/rows \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -H 'Authorization: Bearer access_token' \
  -d '{"title":"my post"}'

レスポンス

正常レスポンス例

{"rows":[{"id":"uuid","title":"my post"}],"next_cursor":null}

異常レスポンス例

{
  "code":"end_user_id_not_writable",
  "message":"end_user_id is managed by the server",
  "detail":{"code":"end_user_id_not_writable","message":"end_user_id is managed by the server"}
}

エラー

•403 table_not_public

•400 end_user_id_not_writable

•404 not_found (table not found)

•401 invalid_session

•403 client_scope_denied

補足

💡行は end_user_id により認証済みエンドユーザへ自動的にスコープされます。

💡body に end_user_id を含めると 400 end_user_id_not_writable を返します。

PATCH

公開行（取得 / 更新 / 削除）公開クライアント

/:api_base/v1/public/tables/{table_name}/rows/{row_id}

ID を指定して現在のエンドユーザの行を取得・部分更新・削除します。

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

Authorization: Bearer <access_token>

パスパラメータ

フィールド	型	必須	説明
table_name	string	必須	テーブル名（小文字・英数字・アンダースコア）
row_id	uuid	必須	行 ID（UUID）

リクエストボディ

フィールド	型	必須	説明
<column>	any	任意	行のカラム名と値のペア

リクエスト例

curl -X PATCH /org_demo_payments/v1/public/tables/posts/rows/<row_id> \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -H 'Authorization: Bearer access_token' \
  -d '{"title":"edited"}'

レスポンス

正常レスポンス例

{"id":"uuid","title":"edited"}

エラー

•404 not_found (row not found)

•403 table_not_public

•400 end_user_id_not_writable

•401 invalid_session

•403 client_scope_denied

リレー

リソースサーバへのプロキシ・非同期ディスパッチ・ルートポリシー

4 エンドポイント

POST

リレープロキシ

公開サーバ

/:api_base/v1/public/relay/{resource_server_id}/{path}

/:api_base/v1/relay/{resource_server_id}/{path}

設定済みリソースサーバの上流へ任意メソッドをプロキシし、レスポンスをそのまま返します。

使用するパス:/:api_base/v1/public/relay/{resource_server_id}/{path}

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

Authorization: Bearer <access_token> (for owner-bound resource servers)

パスパラメータ

フィールド	型	必須	説明
resource_server_id	string	必須	リソースサーバ ID（rs_...）
path	string	必須	リソースサーバのターゲットに付加される上流パス

リクエスト例

curl -X POST /org_demo_payments/v1/public/relay/rs_xxx/v1/messages \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -H 'Authorization: Bearer access_token' \
  -d '{"text":"hello upstream"}'

レスポンス

正常レスポンス例

(the upstream response is returned verbatim, including status and headers)

エラー

•404 resource_server_not_found

•409 relay_target_unconfigured

•502 relay_failed

•504 relay_timeout

•503 tunnel_unavailable

•413 relay_body_too_large

•403 client_scope_denied

補足

💡公開クライアントは relay:proxy スコープが必要です。オーナー紐づけ済みリソースサーバはそのオーナーのエンドユーザのみアクセスできます。

💡本番のリクエストボディ上限は 1MB です（デプロイ毎に変更可）。

💡X-CommonRock-Idempotency-Key はそのまま転送され、非冪等フォールバック時に重複配信の排除に使われます。

POST

リレーディスパッチ（非同期）

公開サーバ

/:api_base/v1/public/relay/{resource_server_id}/dispatch-async

/:api_base/v1/relay/{resource_server_id}/dispatch-async

リレーリクエストをバックグラウンド配送に投入し、上流レスポンスをポーリングします。

使用するパス:/:api_base/v1/public/relay/{resource_server_id}/dispatch-async

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

パスパラメータ

フィールド	型	必須	説明
resource_server_id	string	必須	リソースサーバ ID（rs_...）

リクエストボディ

フィールド	型	必須	説明
method	string	任意	ディスパッチする HTTP メソッド（既定 GET）
path	string	必須	リソースサーバのターゲットに付加される上流パス
query	string	任意	生のクエリ文字列（最大4096文字）
headers	object	任意	上流へ転送するヘッダ名/値のマップ
body_base64	string	任意	Base64 エンコードしたリクエストボディ

リクエスト例

curl -X POST /org_demo_payments/v1/public/relay/rs_xxx/dispatch-async \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***' \
  -d '{"method":"POST","path":"v1/messages","body_base64":"eyJ0ZXh0IjoiaGkifQ=="}'

レスポンス

レスポンス項目

フィールド	型	必須	説明
job_id	string	必須	非同期ジョブ ID
status	string	必須	queued / running / succeeded / failed
submitted_at	datetime	必須	ジョブ受理時刻（ISO8601）
expires_at	datetime	必須	ジョブと結果の有効期限（ISO8601）
relay_mode	string	必須	解決された relay mode（public / wireguard_push / local_agent）

正常レスポンス例

{
  "job_id":"uuid",
  "status":"queued",
  "submitted_at":"2026-06-12T01:00:00Z",
  "expires_at":"2026-06-12T01:05:00Z",
  "relay_mode":"wireguard_push"
}

エラー

•404 resource_server_not_found

•409 relay_target_unconfigured

•400 bad_request / invalid_path (path or query validation)

•413 relay_body_too_large

•403 client_scope_denied

補足

💡202 と job_id を返します。結果はリレージョブエンドポイントから取得します。

💡path は必須・スキーム無し・最大2048文字、query は最大4096文字です。

💡dispatch-async-http/{path} は HTTP リクエスト自体から method/path/body を取る簡易版です。

GET

リレージョブのステータス

公開サーバ

/:api_base/v1/public/relay/jobs/{job_id}

/:api_base/v1/relay/jobs/{job_id}

リレージョブのステータスを取得、または完了までロングポーリングします。

使用するパス:/:api_base/v1/public/relay/jobs/{job_id}

リクエスト

ヘッダ

X-Client-Id: <client_id>

X-Client-Key: <client_key>

Origin: https://app.example.com

パスパラメータ

フィールド	型	必須	説明
job_id	string	必須	非同期ジョブ ID

クエリパラメータ

フィールド	型	必須	説明
timeout_sec	int	任意	待機タイムアウト秒数。1〜300（既定30）

リクエスト例

# Poll once
curl /org_demo_payments/v1/public/relay/jobs/<job_id> \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***'

# Long-poll up to 30s
curl '/org_demo_payments/v1/public/relay/jobs/<job_id>/wait?timeout_sec=30' \
  -H 'Origin: https://app.example.com' \
  -H 'X-Client-Id: pk_live_***' \
  -H 'X-Client-Key: pk_live_***'

レスポンス

レスポンス項目

フィールド	型	必須	説明
job_id	string	必須	非同期ジョブ ID
status	string	必須	queued / running / succeeded / failed
response_status_code	int	任意	上流の HTTP ステータスコード
response_headers	object	任意	上流のレスポンスヘッダ
response_body_base64	string	任意	Base64 エンコードした上流のレスポンスボディ

正常レスポンス例

{
  "job_id":"uuid",
  "status":"succeeded",
  "response_status_code":200,
  "response_headers":{"content-type":"application/json"},
  "response_body_base64":"eyJvayI6dHJ1ZX0="
}

異常レスポンス例

{
  "code":"relay_job_not_found",
  "message":"Relay job not found",
  "detail":{"code":"relay_job_not_found","message":"Relay job not found"}
}

エラー

•404 relay_job_not_found

•401 invalid_client_key / invalid_api_key

補足

💡/wait は timeout_sec（1〜300、既定30）まで完了をブロックして待ちます。

💡終了時、ジョブは response_status_code / response_headers / response_body_base64 を持ちます。

PATCH

リレールートポリシーサーバ専用

/:api_base/v1/relay/{resource_server_id}/policies

push トンネル断時に使うルート別フォールバックポリシーを管理します。

リクエスト

ヘッダ

X-API-Key: <raw_api_key>

パスパラメータ

フィールド	型	必須	説明
resource_server_id	string	必須	リソースサーバ ID（rs_...）

リクエストボディ

フィールド	型	必須	説明
method	string	必須	ポリシーが一致する HTTP メソッド（任意は *）
path_pattern	string	必須	ポリシーが一致するパスパターン
on_tunnel_down	string	必須	push トンネル断時の挙動：poll または fail
allow_nonidempotent_fallback	boolean	任意	非冪等メソッドのポーリングフォールバックを許可するか

リクエスト例

# List route policies
curl /org_demo_payments/v1/relay/rs_xxx/policies -H 'X-API-Key: sk_live_***'

# Upsert a route policy
curl -X PUT /org_demo_payments/v1/relay/rs_xxx/policies \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_***' \
  -d '{"method":"POST","path_pattern":"/v1/messages","on_tunnel_down":"fail","allow_nonidempotent_fallback":false}'

# Set the per-RS default
curl -X PUT /org_demo_payments/v1/relay/rs_xxx/policy-default \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_***' \
  -d '{"on_tunnel_down":"poll"}'

# Delete a route policy
curl -X DELETE /org_demo_payments/v1/relay/rs_xxx/policies/<policy_id> -H 'X-API-Key: sk_live_***'

レスポンス

正常レスポンス例

{
  "policies":[
    {"id":"uuid","method":"POST","path_pattern":"/v1/messages","on_tunnel_down":"fail","allow_nonidempotent_fallback":false}
  ],
  "default_on_tunnel_down":"poll"
}

エラー

•404 resource_server_not_found

•404 relay_route_policy_not_found

•400 invalid_on_tunnel_down / invalid_method / invalid_path_pattern

•401 missing_api_key / invalid_api_key

補足

💡ポリシーは PUT、RS 既定は policy-default で更新します。DELETE は ID 指定で個別削除します。

💡on_tunnel_down は poll または fail。allow_nonidempotent_fallback は非冪等メソッドのポーリングフォールバックを許可します。

認証

セッションイントロスペクション

1 エンドポイント

POST

イントロスペクションサーバ専用

/:api_base/v1/sessions/introspect

トークンが有効かを他サーバから検証します。

リクエスト

ヘッダ

X-API-Key: <secret_api_key>

リクエストボディ

フィールド	型	必須	説明
token	string	任意	アクセストークン
required_scopes	string[]	任意	将来拡張用（現在未使用）

リクエスト例

curl -X POST /org_demo_payments/v1/sessions/introspect \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_***' \
  -d '{"token":"access_token"}'

レスポンス

レスポンス項目

フィールド	型	必須	説明
active	boolean	必須	有効なら true
project_id	uuid	任意	プロジェクトID
end_user_id	uuid	任意	エンドユーザID
session_id	uuid	任意	セッションID
expires_at	datetime	任意	有効期限

正常レスポンス例

{"active":true,"project_id":"uuid","end_user_id":"uuid","session_id":"uuid","expires_at":"2026-02-04T13:00:00Z"}

異常レスポンス例

{
  "code":"invalid_api_key",
  "message":"Invalid API key",
  "detail":{"code":"invalid_api_key","message":"Invalid API key"}
}

エラー

•401 missing_api_key

•401 invalid_api_key

•403 restrictions_required

•403 origin_required

•403 origin_denied

•403 ip_denied

•429 rate_limited

補足

💡シークレットキーはサーバ間のみで利用し、クライアントに公開しない。

レート制限

シークレット API キーはプランごとにレート制限されます。上限に達すると API は 429 rate_limited を返します。

プラン	リクエスト/秒	バースト
Free	60	240
Pro	200	800
Max	1000	4000
Enterprise	無制限	無制限

429 レスポンスには ratelimit-limit / ratelimit-remaining / ratelimit-reset / retry-after ヘッダに加えて、どのバケットに当たったかを示す x-ratelimit-reason（submit / service_plan / secret_plan / public_client）が付きます。

リソースサーバは Portal のリレータブルから RS 単位のリレーレート制限（relay_rate_limit_rps / burst）を追加設定できます。

エラーハンドリング

2xx 以外のレスポンスはすべて同じ構造化エンベロープを使います。code と message はトップレベルと detail の両方に重複します。

Code	HTTP	説明
invalid_credentials	401	認証情報が不正
totp_required	403	TOTPコードが必要
invalid_totp	401	TOTPコードが不正
project_not_found	404	プロジェクトが見つからない
invalid_cursor	400	カーソルが不正
invalid_sql	400	SQLが不正
sql_too_complex	400	SQL複雑度超過
missing_api_key	401	APIキーが未指定
invalid_api_key	401	APIキーが不正
restrictions_required	403	制限が未設定
origin_required	403	Originヘッダ必須
origin_denied	403	Originが許可されていない
ip_denied	403	IPが許可されていない
invalid_public_scopes	400	公開スコープが不正
sql_template_not_found	404	SQLテンプレートがない
maintenance_mode	503	メンテナンス中
csrf_failed	403	CSRF検証失敗
rate_limited	429	レート制限に到達
invalid_session	401	セッションが無効または失効しています。再認証してください。
invalid_refresh_token	401	リフレッシュトークンが無効か使用済みです。再認証してください。
account_locked	403	失敗回数が多すぎるため、アカウントが一時的にロックされています。
authorization_required	401	このテンプレートにはエンドユーザのアクセストークンが必要です。
service_busy	503	サービスが一時的に混雑しています。バックオフして再試行してください。
validation_error	422	リクエスト検証に失敗しました。detail.errors[] を参照してください。
external_id_conflict	409	external_id は既に登録済みです。
template_not_found	404	SQLテンプレートがない
template_server_only	403	このテンプレートはサーバ専用で、公開クライアントからは呼べません。
relay_failed	502	リレー上流に到達できませんでした。
relay_timeout	504	リレー上流が時間内に応答しませんでした。
tunnel_unavailable	503	リレーの push トンネルが利用できず、フォールバックも無効です。
relay_body_too_large	413	リレーのリクエストボディが上限を超えています。

上記の表は安定したクライアント契約エラーコードの一覧です。各エンドポイント固有のエラーは API リファレンスの各エンドポイント詳細を参照してください。

エラーエンベロープ

2xx 以外のレスポンスはすべて同じ JSON エンベロープを使います。code と message はトップレベルと detail の両方に重複します。detail には title / recovery / action_kind / action_label と、（検証エラー時は）errors[] が含まれることがあります。

{
  "code": "invalid_session",
  "message": "Invalid session",
  "detail": {
    "code": "invalid_session",
    "message": "Invalid session",
    "title": "Session expired",
    "recovery": "Sign in again to continue.",
    "action_kind": "reauth",
    "action_label": "Sign in"
  }
}

バリデーション (422)

検証エラーは HTTP 422・code=validation_error で、フィールドエラーの配列が detail.errors[] に入ります。

{
  "code": "validation_error",
  "message": "Invalid request parameters",
  "detail": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "errors": [
      {"field": "external_id", "code": "external_id_required", "message": "external_id is required"}
    ]
  }
}

シークレットキー認証エラー

{
  "code": "rate_limited",
  "message": "Rate limit exceeded",
  "detail": {"code": "rate_limited", "message": "Rate limit exceeded"}
}

リトライ vs 再認証

503 service_busy やその他の 5xx は一過性として扱い、指数バックオフで再試行してください。一方、401 invalid_session と 401 invalid_refresh_token は認証情報が無効になったことを意味します。リトライせず再認証してください（再ログイン、またはリフレッシュトークンのローテーション）。429 rate_limited は retry-after / ratelimit-reset の窓が過ぎるまでバックオフしてください。

変更履歴

API変更履歴を時系列で掲載します。

2026-06-11

リソースサーバ単位の署名鍵、エンドユーザ identity assertion（X-CommonRock-Relay-Assertion JWT）、公開クライアント単位の CORS カスタムヘッダ、RS 単位のレート制限、429 時の x-ratelimit-reason を追加。

2026-06-07

リレーのリバーストンネル（push モード）とルートポリシーによるフォールバック、リレーのレイテンシ改善、リレーエージェント v0.2.0。

2026-06-05

SQL テンプレート：execute_visibility（public / server_only）と公開書き込み向けの :auth.end_user_id オーナー紐づけ。

2026-06-04

リレーのリクエスト/レスポンスのボディ上限を 1MB に引き上げ。

2026-05-30

Database webhooks（Slack 宛先）を一般提供開始。

2026-05-10

プラン別シークレット API レート制限（Free 60rps / Pro 200rps / Max 1000rps、Enterprise 無制限）。

2026-02-28 · 破壊的変更

SQL テンプレート更新 API が SQL/名称の更新とバージョン履歴に対応。

2026-02-28

API キーの利用サマリ、SQL プレイグラウンド、エラーコードリファレンスの拡充を追加。

2026-02-18

非同期 SQL 実行モードとリレー改善を追加。