docs: enhance task creation authentication details#115
Open
pradipthaadhi wants to merge 1 commit intomainfrom
Open
docs: enhance task creation authentication details#115pradipthaadhi wants to merge 1 commit intomainfrom
pradipthaadhi wants to merge 1 commit intomainfrom
Conversation
- Added section on identity binding for task creation in authentication documentation. - Updated OpenAPI specification to clarify authentication requirements and error responses for `POST /api/tasks`. - Revised task creation documentation to emphasize the need for server-derived account identity and the handling of `account_id` authorization checks.
📝 WalkthroughWalkthroughAPI documentation and OpenAPI specification updates clarify authentication and authorization requirements for the POST /api/tasks endpoint. Changes specify that servers must derive account identity from credentials rather than trusting client-supplied account_id, and define security requirements and error responses (401, 403) in the specification. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/openapi.json`:
- Around line 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.
In `@api-reference/tasks/create.mdx`:
- Around line 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 00021b8f-c3e9-4fb6-b63d-fae85feb5e08
📒 Files selected for processing (3)
api-reference/openapi.jsonapi-reference/tasks/create.mdxauthentication.mdx
Comment on lines
+81
to
+89
| "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": [] | ||
| } | ||
| ], |
There was a problem hiding this comment.
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.
Comment on lines
+6
to
+10
| 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`. |
There was a problem hiding this comment.
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.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 3 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/tasks/create.mdx">
<violation number="1" location="api-reference/tasks/create.mdx:6">
P2: Keep API reference MDX pages frontmatter-only; move this endpoint text into `openapi.json` instead.</violation>
</file>
<file name="api-reference/openapi.json">
<violation number="1" location="api-reference/openapi.json:81">
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).`</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| }, | ||
| "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).", |
There was a problem hiding this comment.
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).", |
| openapi: 'POST /api/tasks' | ||
| --- | ||
|
|
||
| Creates a scheduled task. |
There was a problem hiding this comment.
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
POST /api/tasks.account_idauthorization checks.Summary by CodeRabbit
Release Notes