docs: API users (#5620)

* docs: audit, deploymentconfig, files, parameters * Swagger comments in workspacebuilds.go * structs in workspacebuilds.go * workspaceagents: instance identity * workspaceagents.go in progress * workspaceagents.go in progress * Agents * workspacebuilds.go * /workspaces * templates.go, templateversions.go * templateversion.go in progress * cancel * templateversions * wip * Merge * x-apidocgen * NullTime hack not needed anymore * Fix: x-apidocgen * Members * Fixes * Fix * WIP * WIP * Users * Logout * User profile * Status suspend activate * User roles * User tokens * Keys * SSH key * All * Typo * Fix * Fix * Fix: LoginWithPasswordRequest
2025-07-08 11:39:50 +00:00 · 2023-01-11 14:08:04 +01:00
parent 84120767a7
commit 8e9cbdd71b
27 changed files with 4469 additions and 113 deletions
--- a/coderd/apidoc/docs.go
+++ b/coderd/apidoc/docs.go
--- a/coderd/apidoc/swagger.json
+++ b/coderd/apidoc/swagger.json
--- a/coderd/apikey.go
+++ b/coderd/apikey.go
@ -25,6 +25,16 @@ import (
 )

 // Creates a new token API key that effectively doesn't expire.
+//
+// @Summary Create token API key
+// @ID create-token-api-key
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Param request body codersdk.CreateTokenRequest true "Create token request"
+// @Success 201 {object} codersdk.GenerateAPIKeyResponse
+// @Router /users/{user}/keys/tokens [post]
 func (api *API) postToken(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	user := httpmw.UserParam(r)
@ -78,6 +88,15 @@ func (api *API) postToken(rw http.ResponseWriter, r *http.Request) {
 }

 // Creates a new session key, used for logging in via the CLI.
+//
+// @Summary Create new session key
+// @ID create-new-session-key
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 201 {object} codersdk.GenerateAPIKeyResponse
+// @Router /users/{user}/keys [post]
 func (api *API) postAPIKey(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	user := httpmw.UserParam(r)
@ -106,12 +125,21 @@ func (api *API) postAPIKey(rw http.ResponseWriter, r *http.Request) {
 	}

 	// We intentionally do not set the cookie on the response here.
-	// Setting the cookie will couple the browser sesion to the API
+	// Setting the cookie will couple the browser session to the API
 	// key we return here, meaning logging out of the website would
 	// invalid your CLI key.
 	httpapi.Write(ctx, rw, http.StatusCreated, codersdk.GenerateAPIKeyResponse{Key: cookie.Value})
 }

+// @Summary Get API key
+// @ID get-api-key
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Param keyid path string true "Key ID" format(uuid)
+// @Success 200 {object} codersdk.APIKey
+// @Router /users/{user}/keys/{keyid} [get]
 func (api *API) apiKey(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx  = r.Context()
@ -140,6 +168,14 @@ func (api *API) apiKey(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, convertAPIKey(key))
 }

+// @Summary Get user tokens
+// @ID get-user-tokens
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 200 {array} codersdk.APIKey
+// @Router /users/{user}/keys/tokens [get]
 func (api *API) tokens(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx  = r.Context()
@ -172,6 +208,15 @@ func (api *API) tokens(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, apiKeys)
 }

+// @Summary Delete API key
+// @ID delete-user-tokens
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Param keyid path string true "Key ID" format(uuid)
+// @Success 204
+// @Router /users/{user}/keys/{keyid} [delete]
 func (api *API) deleteAPIKey(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx  = r.Context()
--- a/coderd/coderd.go
+++ b/coderd/coderd.go
@ -485,8 +485,8 @@ func New(options *Options) *API {
 					r.Get("/", api.userByName)
 					r.Put("/profile", api.putUserProfile)
 					r.Route("/status", func(r chi.Router) {
-						r.Put("/suspend", api.putUserStatus(database.UserStatusSuspended))
-						r.Put("/activate", api.putUserStatus(database.UserStatusActive))
+						r.Put("/suspend", api.putSuspendUserAccount())
+						r.Put("/activate", api.putActivateUserAccount())
 					})
 					r.Route("/password", func(r chi.Router) {
 						r.Put("/", api.putUserPassword)
--- a/coderd/gitsshkey.go
+++ b/coderd/gitsshkey.go
@ -12,6 +12,14 @@ import (
 	"github.com/coder/coder/codersdk"
 )

+// @Summary Regenerate user SSH key
+// @ID regenerate-user-ssh-key
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 200 {object} codersdk.GitSSHKey
+// @Router /users/{user}/gitsshkey [put]
 func (api *API) regenerateGitSSHKey(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx               = r.Context()
@ -73,6 +81,14 @@ func (api *API) regenerateGitSSHKey(rw http.ResponseWriter, r *http.Request) {
 	})
 }

+// @Summary Get user Git SSH key
+// @ID get-user-git-ssh-key
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 200 {object} codersdk.GitSSHKey
+// @Router /users/{user}/gitsshkey [get]
 func (api *API) gitSSHKey(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	user := httpmw.UserParam(r)
--- a/coderd/members.go
+++ b/coderd/members.go
@ -22,9 +22,9 @@ import (
 // @Accept json
 // @Produce json
 // @Tags Members
-// @Param request body codersdk.UpdateRoles true "Update roles request"
 // @Param organization path string true "Organization ID"
-// @Param user path string true "Username, UUID, or me"
+// @Param user path string true "User ID, name, or me"
+// @Param request body codersdk.UpdateRoles true "Update roles request"
 // @Success 200 {object} codersdk.OrganizationMember
 // @Router /organizations/{organization}/members/{user}/roles [put]
 func (api *API) putMemberRoles(rw http.ResponseWriter, r *http.Request) {
--- a/coderd/roles.go
+++ b/coderd/roles.go
@ -11,6 +11,14 @@ import (
 )

 // assignableSiteRoles returns all site wide roles that can be assigned.
+//
+// @Summary Get site member roles
+// @ID get-site-member-roles
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Members
+// @Success 200 {array} codersdk.AssignableRoles
+// @Router /users/roles [get]
 func (api *API) assignableSiteRoles(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	actorRoles := httpmw.UserAuthorization(r)
@ -23,6 +31,8 @@ func (api *API) assignableSiteRoles(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, assignableRoles(actorRoles.Roles, roles))
 }

+// assignableSiteRoles returns all org wide roles that can be assigned.
+//
 // @Summary Get member roles by organization
 // @ID get-member-roles-by-organization
 // @Security CoderSessionToken
@ -31,8 +41,6 @@ func (api *API) assignableSiteRoles(rw http.ResponseWriter, r *http.Request) {
 // @Param organization path string true "Organization ID" format(uuid)
 // @Success 200 {array} codersdk.AssignableRoles
 // @Router /organizations/{organization}/members/roles [get]
-//
-// assignableSiteRoles returns all site wide roles that can be assigned.
 func (api *API) assignableOrgRoles(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	organization := httpmw.OrganizationParam(r)
--- a/coderd/templateversions.go
+++ b/coderd/templateversions.go
@ -541,6 +541,9 @@ func (api *API) fetchTemplateVersionDryRunJob(rw http.ResponseWriter, r *http.Re
 // @Produce json
 // @Tags Templates
 // @Param id path string true "Template ID" format(uuid)
+// @Param after_id query string false "After ID" format(uuid)
+// @Param limit query int false "Page limit"
+// @Param offset query int false "Page offset"
 // @Success 200 {array} codersdk.TemplateVersion
 // @Router /templates/{id}/versions [get]
 func (api *API) templateVersionsByTemplate(rw http.ResponseWriter, r *http.Request) {
--- a/coderd/userauth.go
+++ b/coderd/userauth.go
@ -43,6 +43,13 @@ type GithubOAuth2Config struct {
 	AllowTeams         []GithubOAuth2Team
 }

+// @Summary Get authentication methods
+// @ID get-authentication-methods
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Success 200 {object} codersdk.AuthMethods
+// @Router /users/authmethods [get]
 func (api *API) userAuthMethods(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(r.Context(), rw, http.StatusOK, codersdk.AuthMethods{
 		Password: true,
@ -51,6 +58,13 @@ func (api *API) userAuthMethods(rw http.ResponseWriter, r *http.Request) {
 	})
 }

+// @Summary OAuth 2.0 GitHub Callback
+// @ID oauth2-github-callback
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Success 307
+// @Router /users/oauth2/github/callback [get]
 func (api *API) userOAuth2Github(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx   = r.Context()
@ -203,6 +217,13 @@ type OIDCConfig struct {
 	UsernameField string
 }

+// @Summary OpenID Connect Callback
+// @ID oidc-callback
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Success 307
+// @Router /users/oidc/callback [get]
 func (api *API) userOIDC(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx   = r.Context()
--- a/coderd/users.go
+++ b/coderd/users.go
@ -28,6 +28,14 @@ import (
 )

 // Returns whether the initial user has been created or not.
+//
+// @Summary Check initial user created
+// @ID check-initial-user-created
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Success 200 {object} codersdk.Response
+// @Router /users/first [get]
 func (api *API) firstUser(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	userCount, err := api.Database.GetUserCount(ctx)
@ -52,6 +60,16 @@ func (api *API) firstUser(rw http.ResponseWriter, r *http.Request) {
 }

 // Creates the initial user for a Coder deployment.
+//
+// @Summary Create initial user
+// @ID create-initial-user
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Users
+// @Param request body codersdk.CreateFirstUserRequest true "First user request"
+// @Success 201 {object} codersdk.CreateFirstUserResponse
+// @Router /users/first [post]
 func (api *API) postFirstUser(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	var createUser codersdk.CreateFirstUserRequest
@ -135,6 +153,17 @@ func (api *API) postFirstUser(rw http.ResponseWriter, r *http.Request) {
 	})
 }

+// @Summary Get users
+// @ID get-users
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param q query string false "Search query"
+// @Param after_id query string false "After ID" format(uuid)
+// @Param limit query int false "Page limit"
+// @Param offset query int false "Page offset"
+// @Success 200 {object} codersdk.GetUsersResponse
+// @Router /users [get]
 func (api *API) users(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	query := r.URL.Query().Get("q")
@ -214,6 +243,16 @@ func (api *API) users(rw http.ResponseWriter, r *http.Request) {
 }

 // Creates a new user.
+//
+// @Summary Create new user
+// @ID create-new-user
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Users
+// @Param request body codersdk.CreateUserRequest true "Create user request"
+// @Success 201 {object} codersdk.User
+// @Router /users [post]
 func (api *API) postUser(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	auditor := *api.Auditor.Load()
@ -300,6 +339,14 @@ func (api *API) postUser(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusCreated, convertUser(user, []uuid.UUID{req.OrganizationID}))
 }

+// @Summary Delete user
+// @ID delete-user
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 200 {object} codersdk.User
+// @Router /users/{user} [delete]
 func (api *API) deleteUser(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	auditor := *api.Auditor.Load()
@ -355,6 +402,15 @@ func (api *API) deleteUser(rw http.ResponseWriter, r *http.Request) {

 // Returns the parameterized user requested. All validation
 // is completed in the middleware for this route.
+//
+// @Summary Get user by name
+// @ID get-user-by-name
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 200 {object} codersdk.User
+// @Router /users/{user} [get]
 func (api *API) userByName(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	user := httpmw.UserParam(r)
@ -376,6 +432,15 @@ func (api *API) userByName(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, convertUser(user, organizationIDs))
 }

+// @Summary Update user profile
+// @ID update-user-profile
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Param request body codersdk.UpdateUserProfileRequest true "Updated profile"
+// @Success 200 {object} codersdk.User
+// @Router /users/{user}/profile [put]
 func (api *API) putUserProfile(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx               = r.Context()
@ -456,6 +521,30 @@ func (api *API) putUserProfile(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, convertUser(updatedUserProfile, organizationIDs))
 }

+// @Summary Suspend user account
+// @ID suspend-user-account
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 200 {object} codersdk.User
+// @Router /users/{user}/status/suspend [put]
+func (api *API) putSuspendUserAccount() func(rw http.ResponseWriter, r *http.Request) {
+	return api.putUserStatus(database.UserStatusSuspended)
+}
+
+// @Summary Activate user account
+// @ID activate-user-account
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 200 {object} codersdk.User
+// @Router /users/{user}/status/activate [put]
+func (api *API) putActivateUserAccount() func(rw http.ResponseWriter, r *http.Request) {
+	return api.putUserStatus(database.UserStatusActive)
+}
+
 func (api *API) putUserStatus(status database.UserStatus) func(rw http.ResponseWriter, r *http.Request) {
 	return func(rw http.ResponseWriter, r *http.Request) {
 		var (
@ -525,6 +614,15 @@ func (api *API) putUserStatus(status database.UserStatus) func(rw http.ResponseW
 	}
 }

+// @Summary Update user password
+// @ID update-user-password
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Param request body codersdk.UpdateUserPasswordRequest true "Update password request"
+// @Success 204
+// @Router /users/{user}/password [put]
 func (api *API) putUserPassword(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx               = r.Context()
@ -642,6 +740,14 @@ func (api *API) putUserPassword(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusNoContent, nil)
 }

+// @Summary Get user roles
+// @ID get-user-roles
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 200 {object} codersdk.User
+// @Router /users/{user}/roles [get]
 func (api *API) userRoles(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	user := httpmw.UserParam(r)
@ -685,6 +791,16 @@ func (api *API) userRoles(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, resp)
 }

+// @Summary Assign role to user
+// @ID assign-role-to-user
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Param request body codersdk.UpdateRoles true "Update roles request"
+// @Success 200 {object} codersdk.User
+// @Router /users/{user}/roles [put]
 func (api *API) putUserRoles(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx = r.Context()
@ -790,6 +906,15 @@ func (api *API) updateSiteUserRoles(ctx context.Context, args database.UpdateUse
 }

 // Returns organizations the parameterized user has access to.
+//
+// @Summary Get organizations by user
+// @ID get-organizations-by-users
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 200 {array} codersdk.Organization
+// @Router /users/{user}/organizations [get]
 func (api *API) organizationsByUser(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	user := httpmw.UserParam(r)
@ -825,6 +950,15 @@ func (api *API) organizationsByUser(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, publicOrganizations)
 }

+// @Summary Get organization by user and organization name
+// @ID get-organization-by-user-and-organization-name
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Param organizationname path string true "Organization name"
+// @Success 200 {object} codersdk.Organization
+// @Router /users/{user}/organizations/{organizationname} [get]
 func (api *API) organizationByUserAndName(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	organizationName := chi.URLParam(r, "organizationname")
@ -852,6 +986,15 @@ func (api *API) organizationByUserAndName(rw http.ResponseWriter, r *http.Reques
 }

 // Authenticates the user with an email and password.
+//
+// @Summary Log in user
+// @ID log-in-user
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Authorization
+// @Param request body codersdk.LoginWithPasswordRequest true "Login request"
+// @Success 201 {object} codersdk.LoginWithPasswordResponse
+// @Router /users/login [post]
 func (api *API) postLogin(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	var loginWithPassword codersdk.LoginWithPasswordRequest
@ -922,6 +1065,14 @@ func (api *API) postLogin(rw http.ResponseWriter, r *http.Request) {
 }

 // Clear the user's session cookie.
+//
+// @Summary Log out user
+// @ID log-out-user
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Success 200 {object} codersdk.Response
+// @Router /users/logout [post]
 func (api *API) postLogout(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	// Get a blank token cookie.
--- a/coderd/workspacebuilds.go
+++ b/coderd/workspacebuilds.go
@ -191,6 +191,16 @@ func (api *API) workspaceBuilds(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, apiBuilds)
 }

+// @Summary Get workspace build by user, workspace name, and build number
+// @ID get-workspace-build-by-user-workspace-name-and-build-number
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Builds
+// @Param user path string true "User ID, name, or me"
+// @Param workspacename path string true "Workspace name"
+// @Param buildnumber path string true "Build number" format(number)
+// @Success 200 {object} codersdk.WorkspaceBuild
+// @Router /users/{user}/workspace/{workspacename}/builds/{buildnumber} [get]
 func (api *API) workspaceBuildByBuildNumber(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	owner := httpmw.UserParam(r)
--- a/coderd/workspaces.go
+++ b/coderd/workspaces.go
@ -192,12 +192,12 @@ func (api *API) workspaces(rw http.ResponseWriter, r *http.Request) {
 	})
 }

-// @Summary Get workspace metadata by owner and workspace name
-// @ID get-workspace-metadata-by-owner-and-workspace-name
+// @Summary Get workspace metadata by user and workspace name
+// @ID get-workspace-metadata-by-user-and-workspace-name
 // @Security CoderSessionToken
 // @Produce json
 // @Tags Workspaces
-// @Param user path string true "Owner username"
+// @Param user path string true "User ID, name, or me"
 // @Param workspacename path string true "Workspace name"
 // @Param include_deleted query bool false "Return data instead of HTTP 404 if the workspace is deleted"
 // @Success 200 {object} codersdk.Workspace