Dureach

API 認証とクイックスタート

API キーを作成し、認証済みリクエストを送り、顧客向け API の範囲を理解します。

Dureach はバージョン付きの /api/ ルートで顧客向け API リソースを提供します。アプリには内部用の /api/v1/ と /api/v2/ ルートもあります。内部ルートは自動的に公開 API にはなりません。API リファレンス に記載されたパスだけを使ってください。

キーを作成する

  1. アプリで Settings → Integrations を開きます。
  2. API キーの画面を開き、必要最小限のアクセスでキーを作成します。
  3. 分かりやすい名前を付け、連携に必要な scope だけを選び、サーバー側のシークレット管理に一度だけコピーし、ドキュメントや例では YOUR_OAUTH_ACCESS_TOKEN を使います。
  4. キーが公開された場合は revoke して新しいキーを作成します。ブラウザバンドル、URL、スクリーンショット、issue、ログに貼り付けないでください。

認証

Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN ヘッダーでキーを送ります。ブラウザバンドル、URL、スクリーンショット、issue、ログにキーを置かないでください。リクエストはキーを作成したアクティブなワークスペースの範囲になります。

curl --fail-with-body 'https://app.dureach.com/api/v2/webhooks?limit=25' \\
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \\
  -H 'Accept: application/json'

API キーと Webhook の管理リソースは /oauth/service-accounts、/api/v2/webhooks、/api/v2/webhook-events にあります。連携を作成する前に、ワークスペースのアクセス権と利用権限を確認してください。

リクエストとレスポンスの形式

name と空でない scopes 配列を含む JSON ボディでキーを作成します。作成レスポンスには id、name、scopes、key、workspace_id、timestamp_created、timestamp_updated が含まれます。完全なキーは一度だけ返され、その後の読み取りでは安全なプレフィックスだけが表示されます。

{
  "name": "Reporting integration",
  "scopes": ["campaigns:read"]
}

一覧レスポンスは items 配列を使い、next_starting_after を含む場合があります。次のページをリクエストするときはカーソルをそのまま渡します。API キーと Webhook の一覧エンドポイントはデフォルトで 25 件、Webhook と Webhook イベントのページは 100 件までです。Webhook レコードには campaign、name、target_hook_url、event_type、custom_interest_value が含まれ、Webhook イベントには配信状態と再試行フィールドが含まれます。

運用チェックリスト

  1. 文書化されたメソッドとパスをそのまま使います。アプリや runner の非公開ルートは顧客向け API エンドポイントではありません。
  2. ページサイズを制限し、エンドポイントのカーソルまたはページネーションのフィールドに従います。
  3. 401 は無効または revoke 済みの認証、403 は権限または利用権限の失敗として扱います。
  4. 一時的なサーバー障害だけを、制限付き backoff と書き込みの idempotency 戦略を使って再試行します。400、401、403、404、409、429 を無条件に再試行しないでください。
  5. サポート用にリクエスト ID とマスクしたエラーコードを保存します。キーや非公開の payload は保存しません。

Webhook の consumer は idempotent にします。確認応答の前にイベント ID を保存し、設定されている場合は署名を検証し、配信の再試行に対応します。

エラー

API キーのエラーは statusCode、error、message を含む JSON です。新しいエンドポイントでは機械可読な code も含まれる場合があります。400 は無効な入力、401 は認証失敗、403 は認可または利用権限の失敗、404 は不明なリソース、429 はレートまたは利用上限として扱います。4xx レスポンスを無条件に再試行しないでください。

関連ページ

API Webhook と利用上限を確認してください。

認証失敗の表

HTTP ステータス意味対応
400JSON、フィールド、カーソル、または limit が無効。リクエストを検証し、文書化された enum/value を使います。
401bearer キーがない、無効、または revoke 済み。Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN を送り、revoke 済みのキーを交換します。
403scope、role、workspace、またはプランが操作を許可していない。必要な scope を追加するか、workspace admin にアクセスを有効化してもらいます。
404リソースまたはパスが存在しない。バージョン、UUID、公開エンドポイント一覧を確認します。
429レートまたは利用上限。レスポンスの指示に従い、制限付き backoff で再試行します。

安全な確認

まず読み取り専用のリクエストを実行し、レスポンスのワークスペースと items の形式を確認します。next_starting_after は返されたまま保存します。書き込みでは HTTP ステータス、マスクしたエラーコード、リクエスト ID だけを記録します。bearer キーや Webhook payload は絶対にログへ出さないでください。