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

313 lines
9.5 KiB
Markdown
Generated

---
# Code generated by make gen. DO NOT EDIT.
title: Authorization
---
<!-- DO NOT EDIT | GENERATED CONTENT -->
## List API key scopes
### Code samples
```sh
# 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
```json
{
"external": [
"all"
]
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|--------------------------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.ExternalAPIKeyScopes](schemas.md#codersdkexternalapikeyscopes) |
## Check authorization
### Code samples
```sh
# 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
```json
{
"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](schemas.md#codersdkauthorizationrequest) | true | Authorization request |
### Example responses
> 200 Response
```json
{
"property1": true,
"property2": true
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|----------------------------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.AuthorizationResponse](schemas.md#codersdkauthorizationresponse) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Log in user
### Code samples
```sh
# 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
```json
{
"email": "user@example.com",
"password": "string"
}
```
### Parameters
| Name | In | Type | Required | Description |
|--------|------|----------------------------------------------------------------------------------|----------|---------------|
| `body` | body | [codersdk.LoginWithPasswordRequest](schemas.md#codersdkloginwithpasswordrequest) | true | Login request |
### Example responses
> 201 Response
```json
{
"session_token": "string"
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|--------------------------------------------------------------|-------------|------------------------------------------------------------------------------------|
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.LoginWithPasswordResponse](schemas.md#codersdkloginwithpasswordresponse) |
## Change password with a one-time passcode
### Code samples
```sh
# 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
```json
{
"email": "user@example.com",
"one_time_passcode": "string",
"password": "string"
}
```
### Parameters
| Name | In | Type | Required | Description |
|--------|------|------------------------------------------------------------------------------------------------------------------|----------|-------------------------|
| `body` | body | [codersdk.ChangePasswordWithOneTimePasscodeRequest](schemas.md#codersdkchangepasswordwithonetimepasscoderequest) | true | Change password request |
### Responses
| Status | Meaning | Description | Schema |
|--------|-----------------------------------------------------------------|-------------|--------|
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
## Request one-time passcode
### Code samples
```sh
# 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
```json
{
"email": "user@example.com"
}
```
### Parameters
| Name | In | Type | Required | Description |
|--------|------|--------------------------------------------------------------------------------------------|----------|---------------------------|
| `body` | body | [codersdk.RequestOneTimePasscodeRequest](schemas.md#codersdkrequestonetimepasscoderequest) | true | One-time passcode request |
### Responses
| Status | Meaning | Description | Schema |
|--------|-----------------------------------------------------------------|-------------|--------|
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
## Validate user password
### Code samples
```sh
# 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
```json
{
"password": "string"
}
```
### Parameters
| Name | In | Type | Required | Description |
|--------|------|----------------------------------------------------------------------------------------|----------|--------------------------------|
| `body` | body | [codersdk.ValidateUserPasswordRequest](schemas.md#codersdkvalidateuserpasswordrequest) | true | Validate user password request |
### Example responses
> 200 Response
```json
{
"details": "string",
"valid": true
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|------------------------------------------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.ValidateUserPasswordResponse](schemas.md#codersdkvalidateuserpasswordresponse) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Convert user from password to oauth authentication
### Code samples
```sh
# 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
```json
{
"password": "string",
"to_type": ""
}
```
### Parameters
| Name | In | Type | Required | Description |
|--------|------|------------------------------------------------------------------------|----------|----------------------|
| `user` | path | string | true | User ID, name, or me |
| `body` | body | [codersdk.ConvertLoginRequest](schemas.md#codersdkconvertloginrequest) | true | Convert request |
### Example responses
> 201 Response
```json
{
"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](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.OAuthConversionResponse](schemas.md#codersdkoauthconversionresponse) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).