MAAARK API 利用ドキュメント

外部サービス連携向けに、認証、APIキー発行、コンテンツ操作、管理APIまでの実装手順をまとめています。

Base URL: https://api.maaark.jp

1. 認証フロー

運用は2段階です。最初に Supabase JWT で APIキーを発行し、以後は APIキーでコンテンツAPIを利用します。

  • JWT: `Authorization: Bearer <SUPABASE_ACCESS_TOKEN>`
  • APIキー: `x-api-key: <ISSUED_API_KEY>` または `Authorization: Bearer <ISSUED_API_KEY>`

2. APIキー管理API（JWT必須）

POST /api/v1/api-keys

APIキーを発行します。`scope` は `read` / `write`。

curl -X POST "https://api.maaark.jp/api/v1/api-keys" \
  -H "Authorization: Bearer <SUPABASE_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"external-app","scope":"write"}'
GET /api/v1/api-keys
DELETE /api/v1/api-keys/:id

3. コンテンツAPI（APIキー利用）

POST /api/v1/contents
GET /api/v1/contents
GET /api/v1/contents/:id
PATCH /api/v1/contents/:id
DELETE /api/v1/contents/:id
POST /api/v1/contents/:id/open

`scope=read` のAPIキーは読み取り専用です。書き込み操作を実行すると `403 E_FORBIDDEN` を返します。 

curl -X GET "https://api.maaark.jp/api/v1/contents?limit=20" \
  -H "x-api-key: <ISSUED_API_KEY>"

4. 管理API（管理者JWT必須）

GET /api/v1/admin/api-key-usage

APIキー使用状況を集計して返します。`ADMIN_USER_IDS` に含まれるユーザーのみ利用できます。

  • query: `hours`, `limit`, `status(active|revoked|all)`, `sort(totalRequests|rateLimitedRequests|lastUsedAt)`
curl -X GET "https://api.maaark.jp/api/v1/admin/api-key-usage?hours=24&status=all&sort=lastUsedAt" \
  -H "Authorization: Bearer <ADMIN_SUPABASE_ACCESS_TOKEN>"

5. 主なエラーコード

  • `E_AUTH_REQUIRED` (401)
  • `E_AUTH_INVALID` (401)
  • `E_FORBIDDEN` (403)
  • `E_URL_INVALID` (400)
  • `E_URL_DUPLICATED` (409)
  • `E_RATE_LIMITED` (429)

6. セキュリティ注意

  • `service_role` キーをクライアント側に置かない
  • APIキー漏えい時は即時失効（`DELETE /api/v1/api-keys/:id`）
  • 本番運用では `ApiAccessLog` と `429` 発生率を日次監視する