Files
Nick Vigilante 7301cee2c4 fix: list every enum value the API can return in the Swagger spec (#30122)
The API reference is generated from Swagger comments and struct tags,
and several `enums:"..."` tags narrowed a named enum type, so the docs
omitted values the server returns. For example, `User.status` listed
only `active` and `suspended`, not `dormant`, and
`TemplateVersion.warnings` listed `DEPRECATED_PARAMETERS`, which is not
a value of the type.

Remove 34 `enums` tags that narrow or duplicate a named type so the
referenced type's full value list is used. Tags that describe an
intentional subset stay: ACL role fields (which omit the `""` deleted
sentinel used only in update requests), `APIKey.scope`, and plain-string
fields. `Template.provisioner` keeps its tag because `.swaggo` replaces
`ProvisionerType` with `string`.

Also fix enum defects that break code generators:

- The provisioner jobs and daemons `status` query parameters listed
their enum twice (Swagger 2.0 requires unique `enum` items) or with the
wrong type. Both are now `[]codersdk.ProvisionerJobStatus` and
`[]codersdk.ProvisionerDaemonStatus`, matching what each handler parses,
including comma-separated values. The daemons route previously
documented job statuses, which the handler rejects with a 500.
- Replace the `_` zero placeholder of `WatchErrorCode` with `iota + 1`,
so the spec no longer lists 0 or `x-enum-varnames: ["_", ...]`. Wire
values are unchanged.

Where the narrowed tag hid values the server returns, the SDK type now
includes them: `LoginTypeOAuth2ProviderApp`, `BuildReasonAutodelete`,
and `MissingTemplateParameter` widen the generated TypeScript unions.
The dashboard attributes `autodelete` builds to Coder like other system
builds. `APIKey.login_type` and `AuthorizationCheck.action` set explicit
examples so the generated samples stay representative.

`TestSwaggerEnumsNotNarrowed` fails when a property's enum list drops
values of its named type (other than the 15 allowlisted intentional
subsets), lists a value the type lacks, or repeats a value.

Part of DOCS-1122, split from #30121.

---
🤖 Built with AI assistance.
2026-11-10 17:42:30 -05:00

9.5 KiB
Generated

title
title
Authorization

List API key scopes

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/auth/scopes \
  -H 'Accept: application/json'

GET /api/v2/auth/scopes

Example responses

200 Response

{
  "external": [
    "all"
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.ExternalAPIKeyScopes

Check authorization

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/authcheck \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/authcheck

Body parameter

{
  "checks": {
    "property1": {
      "action": "read",
      "object": {
        "any_org": true,
        "organization_id": "string",
        "owner_id": "string",
        "resource_id": "string",
        "resource_type": "*"
      }
    },
    "property2": {
      "action": "read",
      "object": {
        "any_org": true,
        "organization_id": "string",
        "owner_id": "string",
        "resource_id": "string",
        "resource_type": "*"
      }
    }
  }
}

Parameters

Name In Type Required Description
body body codersdk.AuthorizationRequest true Authorization request

Example responses

200 Response

{
  "property1": true,
  "property2": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.AuthorizationResponse

To perform this operation, you must be authenticated. Learn more.

Log in user

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/users/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST /api/v2/users/login

Body parameter

{
  "email": "user@example.com",
  "password": "string"
}

Parameters

Name In Type Required Description
body body codersdk.LoginWithPasswordRequest true Login request

Example responses

201 Response

{
  "session_token": "string"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.LoginWithPasswordResponse

Change password with a one-time passcode

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/users/otp/change-password \
  -H 'Content-Type: application/json'

POST /api/v2/users/otp/change-password

Body parameter

{
  "email": "user@example.com",
  "one_time_passcode": "string",
  "password": "string"
}

Parameters

Name In Type Required Description
body body codersdk.ChangePasswordWithOneTimePasscodeRequest true Change password request

Responses

Status Meaning Description Schema
204 No Content No Content

Request one-time passcode

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/users/otp/request \
  -H 'Content-Type: application/json'

POST /api/v2/users/otp/request

Body parameter

{
  "email": "user@example.com"
}

Parameters

Name In Type Required Description
body body codersdk.RequestOneTimePasscodeRequest true One-time passcode request

Responses

Status Meaning Description Schema
204 No Content No Content

Validate user password

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/users/validate-password \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/users/validate-password

Body parameter

{
  "password": "string"
}

Parameters

Name In Type Required Description
body body codersdk.ValidateUserPasswordRequest true Validate user password request

Example responses

200 Response

{
  "details": "string",
  "valid": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.ValidateUserPasswordResponse

To perform this operation, you must be authenticated. Learn more.

Convert user from password to oauth authentication

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/users/{user}/convert-login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/users/{user}/convert-login

Body parameter

{
  "password": "string",
  "to_type": ""
}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
body body codersdk.ConvertLoginRequest true Convert request

Example responses

201 Response

{
  "expires_at": "2019-08-24T14:15:22Z",
  "state_string": "string",
  "to_type": "",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.OAuthConversionResponse

To perform this operation, you must be authenticated. Learn more.