feat(spec): declare the X-Appwrite-Organization security scheme

The API resolves the current organization for /v1/organization* routes from
the x-appwrite-organization header (app/init/resources/request.php), and
rejects org-scoped API keys that omit it with ORGANIZATION_ID_MISSING. The
spec never described that header, so no generated SDK could send it: the
console and server SDKs have no way to target an organization, and consumers
such as the CLI hand-roll the header instead.

Declare Organization as a security scheme on the console and server platforms
and tag the /v1/organization/projects routes with it, so every generated SDK
gains a setOrganization() setter the same way it gains setProject().

AuthType::ORGANIZATION carries no SDK platform of its own, so routes keep
declaring ADMIN/KEY for reachability and x-appwrite.auth is unchanged (it is
sliced to authCount, and Organization is appended last). Method::getAuth() is
read only by spec generation, so this has no runtime auth effect.

Verified by generating all three specs before and after: the client spec is
byte-identical, operation counts are unchanged (554 server / 608 console),
x-appwrite.auth is unchanged on every operation, and the only diff is the new
scheme plus Organization in the security list of the 5 organization routes.
This commit is contained in:
Chirag Aggarwal committed 2026-07-31 09:14:52 +05:30
1 parent 5bc37d2933
commit 12a262b287
9 files changed
+26 -5

No files matched your search

+1
View File
@@ -273,6 +273,7 @@ const APP_AUTH_TYPE_SESSION = 'Session';
const APP_AUTH_TYPE_JWT = 'JWT';
const APP_AUTH_TYPE_KEY = 'Key';
const APP_AUTH_TYPE_ADMIN = 'Admin';
const APP_AUTH_TYPE_ORGANIZATION = 'Organization';
// Response related
const MAX_OUTPUT_CHUNK_SIZE = 10 * 1024 * 1024; // 10MB
const APP_LIMIT_UPLOAD_CHUNK_SIZE = 5 * 1024 * 1024; // 5MB
@@ -54,7 +54,7 @@ class Create extends Action
description: <<<EOT
Create a new project.
EOT,
auth: [AuthType::ADMIN, AuthType::KEY],
auth: [AuthType::ADMIN, AuthType::KEY, AuthType::ORGANIZATION],
responses: [
new SDKResponse(
code: Response::STATUS_CODE_CREATED,
@@ -42,7 +42,7 @@ class Delete extends Action
description: <<<EOT
Delete a project by its unique ID.
EOT,
auth: [AuthType::ADMIN, AuthType::KEY],
auth: [AuthType::ADMIN, AuthType::KEY, AuthType::ORGANIZATION],
responses: [
new SDKResponse(
code: Response::STATUS_CODE_NOCONTENT,
@@ -37,7 +37,7 @@ class Get extends Action
description: <<<EOT
Get a project.
EOT,
auth: [AuthType::ADMIN, AuthType::KEY],
auth: [AuthType::ADMIN, AuthType::KEY, AuthType::ORGANIZATION],
responses: [
new SDKResponse(
code: Response::STATUS_CODE_OK,
@@ -40,7 +40,7 @@ class Update extends Action
description: <<<EOT
Update a project by its unique ID.
EOT,
auth: [AuthType::ADMIN, AuthType::KEY],
auth: [AuthType::ADMIN, AuthType::KEY, AuthType::ORGANIZATION],
responses: [
new SDKResponse(
code: Response::STATUS_CODE_OK,
@@ -54,7 +54,7 @@ class XList extends Action
description: <<<EOT
Get a list of all projects. You can use the query params to filter your results.
EOT,
auth: [AuthType::ADMIN, AuthType::KEY],
auth: [AuthType::ADMIN, AuthType::KEY, AuthType::ORGANIZATION],
responses: [
new SDKResponse(
code: Response::STATUS_CODE_OK,
+12
View File
@@ -234,6 +234,12 @@ class Specs extends Action
'description' => 'Your secret API key',
'in' => 'header',
],
'Organization' => [
'type' => 'apiKey',
'name' => 'X-Appwrite-Organization',
'description' => 'Your organization ID',
'in' => 'header',
],
'JWT' => [
'type' => 'apiKey',
'name' => 'X-Appwrite-JWT',
@@ -327,6 +333,12 @@ class Specs extends Action
'description' => 'Your secret API key',
'in' => 'header',
],
'Organization' => [
'type' => 'apiKey',
'name' => 'X-Appwrite-Organization',
'description' => 'Your organization ID',
'in' => 'header',
],
'JWT' => [
'type' => 'apiKey',
'name' => 'X-Appwrite-JWT',
+7
View File
@@ -8,4 +8,11 @@ enum AuthType: string
case KEY = APP_AUTH_TYPE_KEY;
case SESSION = APP_AUTH_TYPE_SESSION;
case ADMIN = APP_AUTH_TYPE_ADMIN;
/**
* Scopes a request to an organization via the X-Appwrite-Organization
* header. Carries no platform of its own, so routes must still declare the
* auth types that make them reachable (ADMIN, KEY, ...).
*/
case ORGANIZATION = APP_AUTH_TYPE_ORGANIZATION;
}
@@ -86,6 +86,7 @@ class OpenAPI3 extends Format
'Project' => '<YOUR_PROJECT_ID>',
'ProjectPath' => '<YOUR_PROJECT_ID>',
'Key' => '<YOUR_API_KEY>',
'Organization' => '<YOUR_ORGANIZATION_ID>',
'JWT' => '<YOUR_JWT>',
'Locale' => 'en',
'Mode' => '',