認証
Public API Alpha key を 1 つ作成し、ルートアクセス権限とワークスペースアクセスを確認します。
すべての /api/v1alpha1 request は、Authorization header に API キーを入れて送信します。
curl --fail-with-body "$BASE_URL/api/v1alpha1/videos" \
-H "Authorization: Bearer $DEEPFRAME_API_KEY"API キーは server に置いてください。browser code、log、source control に置かないでください。
Public API Alpha key の作成
Public API Alpha は、alpha 期間中に DeepFrame API へのアクセスを付与する key type です。作成するには、ワークスペース管理者が Settings > Developer または Developer keys を開き、Public API Alpha を選択し、現在の API Terms に同意して、ルートアクセス権限を選択します。Standard API key は alpha surface を呼び出せません。
Public API Alpha にはワークスペース単位の gate もあります。platform admin がワークスペースの alpha opt-in を有効にするまで、API は traffic を受け付けません。正しい API キーでも opt-in されていないワークスペースでは 403 forbidden になります。alpha access のないキーは 404 resource-not-found になります。
ルートアクセス権限
アプリケーションが使う operation に必要な権限だけを選択してください。
| 権限 | operation family |
|---|---|
READ_VIDEOS | GET /videos、GET /videos/{video_id} |
UPLOAD_VIDEOS | POST /videos、GET /videos/{video_id}/upload、PUT /videos/{video_id}/upload/parts、POST /videos/{video_id}/upload/targets、POST /videos/{video_id}/upload/complete、DELETE /videos/{video_id}/upload |
VIEW_INSIGHTS | GET /runs、GET /runs/{run_id}、GET /runs/{run_id}/answers、GET /findings、GET /findings/{finding_id}、GET /reports、GET /reports/{report_id} |
RUN_WORKFLOWS | POST /runs、POST /runs/{run_id}/cancel、profile、report template、POST /runs/{run_id}/reports |
SEARCH_CONTENT | POST /search |
MANAGE_WEBHOOKS | /webhooks のすべての operation |
MANAGE_RULEBOOKS | /rulebooks と /workflows のすべての operation |
upload flow には UPLOAD_VIDEOS と READ_VIDEOS の両方が必要です。前者は upload session を作成して進めるため、後者は動画の processing status を読むために使います。ワークフロー quickstart には RUN_WORKFLOWS と VIEW_INSIGHTS も必要です。
operation に必要な権限を持たない有効なキーは 403 forbidden になります。キーがない、無効、期限切れ、inactive、またはワークスペースに紐づいていない場合は 401 unauthorized になります。
ワークスペース identity はキーから決まります
API はキーからワークスペース identity を決めます。request に tenant_id、organization_id、user_id を追加しないでください。別ワークスペースの resource は、存在しない resource と意図的に区別されず、404 resource-not-found になります。
キーの安全な扱い
- キーを secret manager または environment variable に保存してください。
- 信頼できる server からだけ送信してください。
- キーを表示または log に出さないでください。
- Developer settings から rotate または deactivate してください。
export DEEPFRAME_API_KEY="df_live_..."エラー で problem body を、ポリシー で alpha の安定性と retention を確認してください。