diff --git a/api-reference/openapi.json b/api-reference/openapi.json index cbca4f8..3bfbdd5 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -78,7 +78,15 @@ } }, "post": { - "description": "Create a new scheduled task. All fields are required. The response shape matches the GET endpoint (an array containing the created task).", + "description": "Create a new scheduled task. Authentication is required. The effective account identity must be derived from credentials on the server; client-provided account_id must not be blindly trusted. If account_id is provided and is not within the caller's authorized scope, return 403 Forbidden. The response shape matches the GET endpoint (an array containing the created task).", + "security": [ + { + "apiKeyAuth": [] + }, + { + "bearerAuth": [] + } + ], "requestBody": { "description": "Task to create", "required": true, @@ -102,7 +110,37 @@ } }, "400": { - "description": "Bad request", + "description": "Bad request - missing required fields or invalid body", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Unauthorized - missing or invalid credentials", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Forbidden - account_id is outside caller authorization scope", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { diff --git a/api-reference/tasks/create.mdx b/api-reference/tasks/create.mdx index 99a6e51..77e12b3 100644 --- a/api-reference/tasks/create.mdx +++ b/api-reference/tasks/create.mdx @@ -2,3 +2,9 @@ title: 'Create Task' openapi: 'POST /api/tasks' --- + +Creates a scheduled task. + +Authentication is required (`x-api-key` or `Authorization: Bearer `). The server must resolve the effective account identity from auth context; do not treat client-provided `account_id` as ownership proof. + +If `account_id` is provided and is outside the caller's authorized scope, the API returns `403`. diff --git a/authentication.mdx b/authentication.mdx index c25d42f..4a2881c 100644 --- a/authentication.mdx +++ b/authentication.mdx @@ -93,6 +93,16 @@ Some endpoints accept an `organization_id` parameter. When provided, the API add - A **member** of the organization, or - The **organization account itself** +### Task Mutation Identity Binding (`POST /api/tasks`) + +Task creation is identity-bound. The server must derive the effective account from authenticated credentials (`x-api-key` or `Authorization: Bearer`) and enforce authorization before persisting the task. + +- `account_id` in the JSON body is not a trust signal by itself. +- If provided, `account_id` must be within the caller's authorized scope or the API returns `403`. +- Missing or invalid credentials return `401`. + +See [Create Task](/api-reference/tasks/create). + --- ## Error Responses