Skip to content

Commit 0c80011

Browse files
thomasballingerConvex, Inc.
thomasballinger
authored and
Convex, Inc.
committed
Restructure deployment docs (#41928)
GitOrigin-RevId: 1450a3152cb6436d9112eebd9f77c6f6866a1b0b
1 parent 264f6e7 commit 0c80011

File tree

13 files changed

+580
-333
lines changed

13 files changed

+580
-333
lines changed

‎crates/local_backend/src/environment_variables.rs‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,12 @@ pub struct UpdateEnvVarsRequest {
7676
path = "/update_environment_variables",
7777
request_body = UpdateEnvVarsRequest,
7878
responses((status = 200)),
79+
security(
80+
("Deploy Key" = []),
81+
("OAuth Team Token" = []),
82+
("Team Token" = []),
83+
("OAuth Project Token" = []),
84+
),
7985
)]
8086
pub async fn update_environment_variables(
8187
State(st): State<LocalAppState>,
@@ -120,6 +126,12 @@ pub struct ListEnvVarsResponse {
120126
responses(
121127
(status = 200, body = ListEnvVarsResponse)
122128
),
129+
security(
130+
("Deploy Key" = []),
131+
("OAuth Team Token" = []),
132+
("Team Token" = []),
133+
("OAuth Project Token" = []),
134+
),
123135
)]
124136
pub async fn list_environment_variables(
125137
State(st): State<LocalAppState>,

‎crates/local_backend/src/router.rs‎

Lines changed: 82 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,15 @@ use tower_http::{
4343
decompression::RequestDecompressionLayer,
4444
};
4545
use udf::HTTP_ACTION_BODY_LIMIT;
46-
use utoipa::OpenApi;
46+
use utoipa::{
47+
openapi::security::{
48+
ApiKey,
49+
ApiKeyValue,
50+
SecurityScheme,
51+
},
52+
Modify,
53+
OpenApi,
54+
};
4755
use utoipa_axum::router::OpenApiRouter;
4856

4957
use crate::{
@@ -152,17 +160,87 @@ use crate::{
152160
RouterState,
153161
};
154162

155-
// TODO security per endpoint
163+
// Security addon for documenting authentication methods
164+
#[derive(Debug)]
165+
struct SecurityAddon;
166+
167+
impl Modify for SecurityAddon {
168+
fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
169+
if let Some(schema) = openapi.components.as_mut() {
170+
/*
171+
// Admin keys look just like deployment keys but there's no need to
172+
// contact api.convex.dev to validate them) and cannot be revoked.
173+
// The Convex Cloud product avoids giving them out.
174+
// We can document this once the distinction between these is clearer.
175+
schema.add_security_scheme(
176+
"Admin Key",
177+
SecurityScheme::Http(
178+
HttpBuilder::new()
179+
.scheme(HttpAuthScheme::Bearer)
180+
.description(Some(
181+
"Admin keys provide full access to a deployment. Created in the \
182+
[dashboard](https://docs.convex.dev/dashboard/deployments/deployment-settings#url-and-deploy-key) \
183+
or via API. Use the `Convex ` prefix (e.g., `Convex <admin_key>`).",
184+
))
185+
.build(),
186+
),
187+
);
188+
*/
189+
schema.add_security_scheme(
190+
"Deploy Key",
191+
SecurityScheme::ApiKey(ApiKey::Header(
192+
ApiKeyValue::with_description(
193+
"Authorization",
194+
"Deploy keys are used for deployment operations. See \
195+
[deploy key types](https://docs.convex.dev/cli/deploy-key-types) for more information. \
196+
Use the `Convex ` prefix (e.g., `Convex <deploy_key>`).",
197+
),
198+
)),
199+
);
200+
schema.add_security_scheme(
201+
"OAuth Team Token",
202+
SecurityScheme::ApiKey(ApiKey::Header(
203+
ApiKeyValue::with_description(
204+
"Authorization",
205+
"Obtained through a [Convex OAuth application](https://docs.convex.dev/management-api). \
206+
Use the `Convex ` prefix (e.g., `Convex <oauth_token>`).",
207+
),
208+
)),
209+
);
210+
schema.add_security_scheme(
211+
"Team Token",
212+
SecurityScheme::ApiKey(ApiKey::Header(ApiKeyValue::with_description(
213+
"Authorization",
214+
"Created in the dashboard under team settings for any team you can manage. \
215+
Use the `Convex ` prefix (e.g., `Convex <team_token>`).",
216+
))),
217+
);
218+
schema.add_security_scheme(
219+
"OAuth Project Token",
220+
SecurityScheme::ApiKey(ApiKey::Header(
221+
ApiKeyValue::with_description(
222+
"Authorization",
223+
"Obtained through a [Convex OAuth application](https://docs.convex.dev/management-api) \
224+
with project scope. Use the `Convex ` prefix (e.g., `Convex <oauth_project_token>`).",
225+
),
226+
)),
227+
);
228+
}
229+
}
230+
}
156231

157232
#[derive(OpenApi)]
158233
#[openapi(
234+
modifiers(&SecurityAddon),
159235
info(
160236
title = "Convex Deployment API",
161237
version = "1.0.0",
162-
description = "Admin API for interacting with deployments",
238+
description = "Admin API for interacting with deployments.",
163239
),
164240
servers(
165-
(url = "/api/v1", description = "Deployment API")
241+
(url = "{deployment-url}/api/v1", description = "Your Convex deployment", variables(
242+
("deployment-url" = (default = "https://happy-animal-123.convex.cloud", description = "Your deployment URL"))
243+
))
166244
)
167245
)]
168246
struct PlatformApiDoc;

‎npm-packages/@convex-dev/platform/deployment-openapi.json‎

Lines changed: 65 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"openapi": "3.1.0",
33
"info": {
44
"title": "Convex Deployment API",
5-
"description": "Admin API for interacting with deployments",
5+
"description": "Admin API for interacting with deployments.",
66
"license": {
77
"name": "LicenseRef-FSL-1.1-Apache-2.0",
88
"identifier": "LicenseRef-FSL-1.1-Apache-2.0"
@@ -11,8 +11,14 @@
1111
},
1212
"servers": [
1313
{
14-
"url": "/api/v1",
15-
"description": "Deployment API"
14+
"url": "{deployment-url}/api/v1",
15+
"description": "Your Convex deployment",
16+
"variables": {
17+
"deployment-url": {
18+
"default": "https://happy-animal-123.convex.cloud",
19+
"description": "Your deployment URL"
20+
}
21+
}
1622
}
1723
],
1824
"paths": {
@@ -35,7 +41,21 @@
3541
"200": {
3642
"description": ""
3743
}
38-
}
44+
},
45+
"security": [
46+
{
47+
"Deploy Key": []
48+
},
49+
{
50+
"OAuth Team Token": []
51+
},
52+
{
53+
"Team Token": []
54+
},
55+
{
56+
"OAuth Project Token": []
57+
}
58+
]
3959
}
4060
},
4161
"/list_environment_variables": {
@@ -54,7 +74,21 @@
5474
}
5575
}
5676
}
57-
}
77+
},
78+
"security": [
79+
{
80+
"Deploy Key": []
81+
},
82+
{
83+
"OAuth Team Token": []
84+
},
85+
{
86+
"Team Token": []
87+
},
88+
{
89+
"OAuth Project Token": []
90+
}
91+
]
5892
}
5993
},
6094
"/update_canonical_url": {
@@ -190,6 +224,32 @@
190224
}
191225
}
192226
}
227+
},
228+
"securitySchemes": {
229+
"Deploy Key": {
230+
"type": "apiKey",
231+
"in": "header",
232+
"name": "Authorization",
233+
"description": "Deploy keys are used for deployment operations. See [deploy key types](https://docs.convex.dev/cli/deploy-key-types) for more information. Use the `Convex ` prefix (e.g., `Convex <deploy_key>`)."
234+
},
235+
"OAuth Project Token": {
236+
"type": "apiKey",
237+
"in": "header",
238+
"name": "Authorization",
239+
"description": "Obtained through a [Convex OAuth application](https://docs.convex.dev/management-api) with project scope. Use the `Convex ` prefix (e.g., `Convex <oauth_project_token>`)."
240+
},
241+
"OAuth Team Token": {
242+
"type": "apiKey",
243+
"in": "header",
244+
"name": "Authorization",
245+
"description": "Obtained through a [Convex OAuth application](https://docs.convex.dev/management-api). Use the `Convex ` prefix (e.g., `Convex <oauth_token>`)."
246+
},
247+
"Team Token": {
248+
"type": "apiKey",
249+
"in": "header",
250+
"name": "Authorization",
251+
"description": "Created in the dashboard under team settings for any team you can manage. Use the `Convex ` prefix (e.g., `Convex <team_token>`)."
252+
}
193253
}
194254
}
195255
}

‎npm-packages/@convex-dev/platform/management-openapi.json‎

Lines changed: 45 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,9 @@
5656
},
5757
"security": [
5858
{
59-
"OAuth Team Token": [],
59+
"OAuth Team Token": []
60+
},
61+
{
6062
"Team Token": []
6163
}
6264
]
@@ -95,7 +97,9 @@
9597
},
9698
"security": [
9799
{
98-
"OAuth Team Token": [],
100+
"OAuth Team Token": []
101+
},
102+
{
99103
"Team Tokens": []
100104
}
101105
]
@@ -134,9 +138,13 @@
134138
},
135139
"security": [
136140
{
137-
"OAuth Project Token": [],
138-
"OAuth Team Token": [],
141+
"OAuth Team Token": []
142+
},
143+
{
139144
"Team Token": []
145+
},
146+
{
147+
"OAuth Project Token": []
140148
}
141149
]
142150
}
@@ -164,7 +172,9 @@
164172
},
165173
"security": [
166174
{
167-
"OAuth Team Token": [],
175+
"OAuth Team Token": []
176+
},
177+
{
168178
"Team Token": []
169179
}
170180
]
@@ -207,9 +217,13 @@
207217
},
208218
"security": [
209219
{
210-
"OAuth Project Token": [],
211-
"OAuth Team Token": [],
220+
"OAuth Team Token": []
221+
},
222+
{
212223
"Team Token": []
224+
},
225+
{
226+
"OAuth Project Token": []
213227
}
214228
]
215229
}
@@ -233,9 +247,13 @@
233247
},
234248
"security": [
235249
{
236-
"OAuth Project Token": [],
237-
"OAuth Team Token": [],
250+
"OAuth Team Token": []
251+
},
252+
{
238253
"Team Token": []
254+
},
255+
{
256+
"OAuth Project Token": []
239257
}
240258
]
241259
}
@@ -269,9 +287,13 @@
269287
},
270288
"security": [
271289
{
272-
"OAuth Project Token": [],
273-
"OAuth Team Token": [],
290+
"OAuth Team Token": []
291+
},
292+
{
274293
"Team Token": []
294+
},
295+
{
296+
"OAuth Project Token": []
275297
}
276298
]
277299
}
@@ -306,9 +328,13 @@
306328
},
307329
"security": [
308330
{
309-
"OAuth Project Token": [],
310-
"OAuth Team Token": [],
331+
"OAuth Team Token": []
332+
},
333+
{
311334
"Team Token": []
335+
},
336+
{
337+
"OAuth Project Token": []
312338
}
313339
]
314340
}
@@ -340,9 +366,13 @@
340366
},
341367
"security": [
342368
{
343-
"OAuth Project Token": [],
344-
"OAuth Team Token": [],
369+
"OAuth Team Token": []
370+
},
371+
{
345372
"Team Token": []
373+
},
374+
{
375+
"OAuth Project Token": []
346376
}
347377
]
348378
}

0 commit comments

Comments
 (0)