Skip to content

docs: enhance task creation authentication details #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pradipthaadhi wants to merge 1 commit into
base: main
Choose a base branch
from
+56 −2
Open

docs: enhance task creation authentication details #115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 40 additions & 2 deletions api-reference/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).",
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai bot Apr 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: The description says "If account_id is provided…" implying it's optional, but CreateTaskRequest still lists account_id in the required array. This inconsistency will cause generated SDKs and docs to contradict each other. Either remove account_id from required (and update its property description to say it's optional/server-derived), or reword this description to reflect that it is always required.

Also, "an array containing the created task" is inaccurate — TasksResponse is an object with a tasks array, not a bare array. Consider: The response shape matches the GET endpoint (TasksResponse, with the created task in the tasks array).

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi.json, line 81:

<comment>The description says "If account_id is provided…" implying it's optional, but `CreateTaskRequest` still lists `account_id` in the `required` array. This inconsistency will cause generated SDKs and docs to contradict each other. Either remove `account_id` from `required` (and update its property description to say it's optional/server-derived), or reword this description to reflect that it is always required.

Also, "an array containing the created task" is inaccurate — `TasksResponse` is an object with a `tasks` array, not a bare array. Consider: `The response shape matches the GET endpoint (TasksResponse, with the created task in the tasks array).`</comment>

<file context>
@@ -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": [
+          {
</file context>
Suggested change
"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).",
"description": "Create a new scheduled task. Authentication is required. The server must derive the caller identity from credentials and authorize any provided account_id override. If an account_id outside the caller's authorized scope is supplied, return 403 Forbidden. The response shape matches the GET endpoint (`TasksResponse`, with the created task in the `tasks` array).",
Fix with Cubic

"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
],
Comment on lines +81 to +89
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Keep the POST /api/tasks contract internally consistent.

Line 81 says account_id is only checked if provided, but #/components/schemas/CreateTaskRequest still marks account_id as required at Line 7450. The same sentence also says the success body is an array, while #/components/schemas/TasksResponse is an object with a tasks array. Generated docs and SDKs will expose contradictory behavior here.

🛠️ Suggested contract alignment 
-        "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).",
+        "description": "Create a new scheduled task. Authentication is required. The server must derive the caller identity from credentials and authorize any provided account_id override. If an account_id outside the caller's authorized scope is supplied, return 403 Forbidden. The response shape matches the GET endpoint (`TasksResponse`, with the created task in the `tasks` array).",
...
       "CreateTaskRequest": {
         "type": "object",
         "required": [
           "title",
           "prompt",
           "schedule",
-          "account_id",
           "artist_account_id"
         ],
         "properties": {
           "account_id": {
             "type": "string",
             "format": "uuid",
-            "description": "UUID of the associated account",
+            "description": "Optional UUID of the target account. If omitted, the server derives it from the authenticated credentials. If provided, it must be within the caller's authorized scope.",
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi.json` around lines 81 - 89, The OpenAPI contract for
POST /api/tasks is inconsistent: the operation description says account_id is
optional and only validated if provided, but the CreateTaskRequest schema
(CreateTaskRequest) currently marks account_id as required, and the description
says the success body is an array while TasksResponse is defined as an object
with a tasks array; fix by aligning schemas and description—either make
account_id optional in CreateTaskRequest (remove it from required) if callers
may omit it, or update the operation text to require and validate account_id if
you intend it required; likewise ensure the response shape matches: change the
operation description to state it returns a TasksResponse object (with tasks
array) or update TasksResponse to be an array type matching the described
response; update the textual description of POST /api/tasks to exactly reflect
the chosen schema changes.

"requestBody": {
"description": "Task to create",
"required": true,
Expand All @@ -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": {
Expand Down
6 changes: 6 additions & 0 deletions api-reference/tasks/create.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,9 @@
title: 'Create Task'
openapi: 'POST /api/tasks'
---

Creates a scheduled task.
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai bot Apr 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Keep API reference MDX pages frontmatter-only; move this endpoint text into openapi.json instead.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/tasks/create.mdx, line 6:

<comment>Keep API reference MDX pages frontmatter-only; move this endpoint text into `openapi.json` instead.</comment>

<file context>
@@ -2,3 +2,9 @@
 openapi: 'POST /api/tasks'
 ---
+
+Creates a scheduled task.
+
+Authentication is required (`x-api-key` or `Authorization: Bearer <token>`). The server must resolve the effective account identity from auth context; do not treat client-provided `account_id` as ownership proof.
</file context>
Fix with Cubic


Authentication is required (`x-api-key` or `Authorization: Bearer <token>`). 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`.
Comment on lines +6 to +10
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Keep API reference pages frontmatter-only.

This body content should not be in api-reference/**/*.mdx. Move these details to the OpenAPI operation description and/or authentication.mdx, and keep this page as frontmatter only.

Suggested minimal change 
 ---
 title: 'Create Task'
 openapi: 'POST /api/tasks'
 ---
-
-Creates a scheduled task.
-
-Authentication is required (`x-api-key` or `Authorization: Bearer <token>`). 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`.

As per coding guidelines, api-reference/**/*.mdx: "API reference MDX pages should be frontmatter-only - do NOT add custom sections (Overview, Availability, etc.) and let Mintlify auto-generate everything from the OpenAPI spec", and **/*.mdx: "Follow DRY principle - don't duplicate content across pages, use snippets instead".

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Creates a scheduled task.
Authentication is required (`x-api-key` or `Authorization: Bearer <token>`). 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`.
---
title: 'Create Task'
openapi: 'POST /api/tasks'
---
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@api-reference/tasks/create.mdx` around lines 6 - 10, The
api-reference/tasks/create.mdx page contains body content that must be removed
and kept frontmatter-only; delete the descriptive paragraphs (e.g., the "Creates
a scheduled task." block and the text about authentication and account_id) and
move that information into the OpenAPI operation description for the Create Task
operation (or into authentication.mdx) so the OpenAPI spec is the single source
of truth; ensure references to account_id and the 403 behavior are documented in
the OpenAPI operation description rather than in api-reference/tasks/create.mdx.

10 changes: 10 additions & 0 deletions authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down