コンテンツにスキップ
Authrim

リクエストとレスポンス

リクエスト形式

HTTPメソッド

メソッド用途
GETリソースの取得
POSTリソースの作成、アクションの実行
PUTリソースの更新（全体置換）
PATCHリソースの部分更新
DELETEリソースの削除

リクエストヘッダー

すべてのリクエストに以下のヘッダーを含めてください：

Authorization: Bearer {admin-api-token}
Content-Type: application/json
Accept: application/json

リクエストボディ

POST、PUT、PATCHリクエストではJSON形式のボディを送信します：

Terminal window
curl -X POST "https://{tenant-domain}/api/admin/users" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "山田 太郎",
    "role": "user"
  }'

レスポンス形式

成功レスポンス

単一リソースの取得

{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "山田 太郎",
  "created_at": 1705881600,
  "updated_at": 1705881600
}

リソースリストの取得

{
  "items": [
    {
      "id": "usr_abc123",
      "email": "[email protected]",
      "name": "山田 太郎"
    },
    {
      "id": "usr_def456",
      "email": "[email protected]",
      "name": "佐藤 花子"
    }
  ],
  "total": 150,
  "cursor": "eyJpZCI6InVzcl9kZWY0NTYifQ=="
}

リソースの作成

リソース作成時は、作成されたリソースの完全な情報が返されます：

{
  "id": "usr_xyz789",
  "email": "[email protected]",
  "name": "新規 ユーザー",
  "created_at": 1705968000,
  "updated_at": 1705968000
}

HTTPステータスコード: 201 Created

リソースの削除

削除成功時は空のレスポンスボディとステータスコード 204 No Content が返されます。

HTTPステータスコード

コード説明
200 OKリクエスト成功
201 Createdリソース作成成功
204 No Content削除成功（ボディなし）
400 Bad Requestリクエストが不正
401 Unauthorized認証失敗
403 Forbidden権限不足
404 Not Foundリソースが見つからない
409 Conflictリソースの競合
422 Unprocessable Entityバリデーションエラー
429 Too Many Requestsレート制限超過
500 Internal Server Errorサーバーエラー

ページネーション

リスト系APIはカーソルベースのページネーションを採用しています。

リクエストパラメータ

パラメータ型デフォルト説明
limitinteger20取得する件数（最大100）
cursorstring-次のページのカーソル

ページネーションの例

最初のページを取得

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/users?limit=20" \
  -H "Authorization: Bearer {token}"

レスポンス：

{
  "items": [...],
  "total": 150,
  "cursor": "eyJpZCI6InVzcl9hYmMxMjMifQ=="
}

次のページを取得

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/users?limit=20&cursor=eyJpZCI6InVzcl9hYmMxMjMifQ==" \
  -H "Authorization: Bearer {token}"

ページネーションの終了判定

cursor が null または空の場合、それ以上のデータはありません：

{
  "items": [...],
  "total": 150,
  "cursor": null
}

フィルタリングとソート

フィルタリング

多くのリスト系APIはクエリパラメータによるフィルタリングをサポートしています：

Terminal window
# ステータスでフィルタ
curl -X GET "https://{tenant-domain}/api/admin/users?status=active" \
  -H "Authorization: Bearer {token}"


# 作成日時でフィルタ
curl -X GET "https://{tenant-domain}/api/admin/users?created_after=1705881600" \
  -H "Authorization: Bearer {token}"


# 複合フィルタ
curl -X GET "https://{tenant-domain}/api/admin/users?status=active&role=admin" \
  -H "Authorization: Bearer {token}"

検索

テキスト検索が可能なエンドポイントでは q または search パラメータを使用します：

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/users?search=yamada" \
  -H "Authorization: Bearer {token}"

ソート

ソートは sort パラメータで指定します：

Terminal window
# 昇順
curl -X GET "https://{tenant-domain}/api/admin/users?sort=created_at" \
  -H "Authorization: Bearer {token}"


# 降順（-プレフィックス）
curl -X GET "https://{tenant-domain}/api/admin/users?sort=-created_at" \
  -H "Authorization: Bearer {token}"

日時形式

タイムスタンプ

APIのタイムスタンプはUNIXエポック秒で表現されます：

{
  "created_at": 1705881600,
  "updated_at": 1705968000
}

日時パラメータ

フィルタリングパラメータとして日時を指定する場合も、UNIXエポック秒を使用します：

Terminal window
# 2024年1月22日以降に作成されたユーザー
curl -X GET "https://{tenant-domain}/api/admin/users?created_after=1705881600" \
  -H "Authorization: Bearer {token}"

日付範囲

統計APIなどでは日付範囲を指定できます：

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/stats/auth?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer {token}"

レート制限

APIにはレート制限が適用されます。制限を超過すると 429 Too Many Requests が返されます。

レート制限ヘッダー

レスポンスには以下のヘッダーが含まれます：

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705885200
ヘッダー説明
X-RateLimit-Limitウィンドウあたりの最大リクエスト数
X-RateLimit-Remaining残りリクエスト数
X-RateLimit-Reset制限がリセットされるUNIXタイムスタンプ

レート制限超過時

{
  "error": "rate_limit_exceeded",
  "error_description": "レート制限を超過しました。しばらく待ってから再試行してください。",
  "retry_after": 60
}

retry_after は再試行可能になるまでの秒数を示します。

べき等性

べき等なリクエスト

GET、PUT、DELETE リクエストはべき等です。同じリクエストを複数回送信しても、結果は同じになります。

Idempotency-Key

POST リクエストでべき等性を確保したい場合は、Idempotency-Key ヘッダーを使用できます：

Terminal window
curl -X POST "https://{tenant-domain}/api/admin/users" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{"email": "[email protected]", "name": "山田 太郎"}'

同じ Idempotency-Key を持つリクエストは、最初のリクエストの結果をキャッシュして返します。