From 03a85c7057c6b4ce8f708009258502ff0697561a Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 4 Jan 2023 14:09:30 +0100 Subject: [PATCH 1/5] docs: improve authentication page --- docs/admin/automation.md | 15 +++---- docs/api/authentication.md | 14 ++++++- .../apidocgen/markdown-template/security.def | 40 +++++++------------ 3 files changed, 31 insertions(+), 38 deletions(-) diff --git a/docs/admin/automation.md b/docs/admin/automation.md index fa1366c429469..62cb28c605782 100644 --- a/docs/admin/automation.md +++ b/docs/admin/automation.md @@ -2,13 +2,9 @@ We recommend automating Coder deployments through the CLI. Examples include [updating templates via CI/CD pipelines](../templates/change-management.md). -## Tokens +## Authentication -Long-lived tokens can be generated to perform actions on behalf of your user account: - -```console -coder tokens create -``` +Coder uses authentication tokens to grant machine users access to the REST API. Follow the [Authentication](../api/authentication.md) page to see how to generate long-lived tokens. ## CLI @@ -23,14 +19,13 @@ coder workspaces ls ## REST API -You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header. +You can review the [API reference](../api/index.md) to find the necessary routes and payload. Alternatively, you can enable the [Swagger](https://swagger.io/) endpoint to play with the API: ```console -curl 'https://dev.coder.com/api/v2/workspaces' \ - -H 'Coder-Session-Token: *****' +coder server --swagger-enable ``` -> At this time, we do not publish an API reference. However, [codersdk](https://github.com/coder/coder/tree/main/codersdk) can be grepped to find the necessary routes and payloads. +By default, the local Swagger endpoint is http://localhost:3000/swagger. ## Golang SDK diff --git a/docs/api/authentication.md b/docs/api/authentication.md index 8c3c209b1ae7c..e0bdb045ee139 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -1,4 +1,14 @@ # Authentication -- API Key (CoderSessionToken) - - Parameter Name: **Coder-Session-Token**, in: header. +Long-lived tokens can be generated to perform actions on behalf of your user account: + +```console +coder tokens create +``` + +You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header. + +```console +curl 'http://coder-server:8080/api/v2/workspaces' \ + -H 'Coder-Session-Token: *****' +``` diff --git a/scripts/apidocgen/markdown-template/security.def b/scripts/apidocgen/markdown-template/security.def index 3414468904c5d..aadaf424b97fd 100644 --- a/scripts/apidocgen/markdown-template/security.def +++ b/scripts/apidocgen/markdown-template/security.def @@ -1,27 +1,15 @@ -{{= data.tags.section }}# Authentication -{{ for (var s in data.api.components.securitySchemes) { }} -{{ var sd = data.api.components.securitySchemes[s]; }} -{{? sd.type == 'apiKey' }} -- API Key ({{=s}}) - - Parameter Name: **{{=sd.name}}**, in: {{=sd.in}}. {{=sd.description || ''}} -{{?}} -{{? sd.type == 'http'}} -- HTTP Authentication, scheme: {{=sd.scheme}}{{? sd.description }}
{{=sd.description}}{{?}} -{{?}} -{{? sd.type == 'oauth2'}} -- oAuth2 authentication. {{=sd.description || ''}} -{{ for (var f in sd.flows) { }} -{{ var flow = sd.flows[f]; }} - - Flow: {{=f}} -{{? flow.authorizationUrl}} - Authorization URL = [{{=flow.authorizationUrl}}]({{=flow.authorizationUrl}}){{?}} -{{? flow.tokenUrl}} - Token URL = [{{=flow.tokenUrl}}]({{=flow.tokenUrl}}){{?}} -{{? flow.scopes && Object.keys(flow.scopes).length}} -|Scope|Scope Description| -|---|---| -{{ for (var sc in flow.scopes) { }}|{{=sc}}|{{=data.utils.join(flow.scopes[sc])}}| -{{ } /* of scopes */ }} -{{?}} -{{ } /* of flows */ }} -{{?}} -{{ } /* of securitySchemes */ }} +# Authentication + +Long-lived tokens can be generated to perform actions on behalf of your user account: + +```console +coder tokens create +``` + +You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header. + +```console +curl 'http://coder-server:8080/api/v2/workspaces' \ + -H 'Coder-Session-Token: *****' +``` From 516f465b5e431f3452430316350d99be62b8f06f Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 4 Jan 2023 14:53:18 +0100 Subject: [PATCH 2/5] Update docs/admin/automation.md Co-authored-by: Mathias Fredriksson --- docs/admin/automation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/automation.md b/docs/admin/automation.md index 62cb28c605782..cd9be9f4dff4c 100644 --- a/docs/admin/automation.md +++ b/docs/admin/automation.md @@ -19,7 +19,7 @@ coder workspaces ls ## REST API -You can review the [API reference](../api/index.md) to find the necessary routes and payload. Alternatively, you can enable the [Swagger](https://swagger.io/) endpoint to play with the API: +You can review the [API reference](../api/index.md) to find the necessary routes and payload. Alternatively, you can enable the [Swagger](https://swagger.io/) endpoint to read the documentation and do requests against the API: ```console coder server --swagger-enable From 8522e7ec3140434bff73e4cb125900e8dcc1980d Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 4 Jan 2023 14:53:25 +0100 Subject: [PATCH 3/5] Update docs/admin/automation.md Co-authored-by: Mathias Fredriksson --- docs/admin/automation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/automation.md b/docs/admin/automation.md index cd9be9f4dff4c..1ddec90bbc360 100644 --- a/docs/admin/automation.md +++ b/docs/admin/automation.md @@ -4,7 +4,7 @@ We recommend automating Coder deployments through the CLI. Examples include [upd ## Authentication -Coder uses authentication tokens to grant machine users access to the REST API. Follow the [Authentication](../api/authentication.md) page to see how to generate long-lived tokens. +Coder uses authentication tokens to grant machine users access to the REST API. Follow the [Authentication](../api/authentication.md) page to learn how to generate long-lived tokens. ## CLI From 47e2d2a6622e2c28cc327261e7a3001deb95a630 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 4 Jan 2023 14:54:20 +0100 Subject: [PATCH 4/5] Fix --- docs/api/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/authentication.md b/docs/api/authentication.md index e0bdb045ee139..b3c5ee5dd7bd8 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -6,7 +6,7 @@ Long-lived tokens can be generated to perform actions on behalf of your user acc coder tokens create ``` -You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header. +You can use the created tokens with Coder's REST API by setting the `Coder-Session-Token` HTTP header. ```console curl 'http://coder-server:8080/api/v2/workspaces' \ From fd65cfe1e0a3d8654eb556b1c90661e24a5944d2 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 4 Jan 2023 15:02:44 +0100 Subject: [PATCH 5/5] Fix --- docs/api/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/authentication.md b/docs/api/authentication.md index b3c5ee5dd7bd8..e0bdb045ee139 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -6,7 +6,7 @@ Long-lived tokens can be generated to perform actions on behalf of your user acc coder tokens create ``` -You can use the created tokens with Coder's REST API by setting the `Coder-Session-Token` HTTP header. +You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header. ```console curl 'http://coder-server:8080/api/v2/workspaces' \